TypeScript SDK

@invokehq/sdk is the whole integration. It has one method that matters: invoke.call().

import { Invoke } from "@invokehq/sdk"

const invoke = Invoke.fromEnv()

const done = await invoke.call({
  tool: "linear.update_issue",
  params: { issue_id: "DRA-8", state: "Done" },
  agentId: "coding-agent",
  idempotencyKey: "DRA-8:done",
})

done.receipt.number // "#e59a65d7": signed proof it happened

The contract. If call() resolves, the action happened and you hold its receipt; a repeat of the same call returns that same receipt instead of acting again. If it didn’t happen, call() throws, and the error’s class tells you whether it happened.

Install

npm install @invokehq/sdk

Node 20+. No dependencies. ESM, with TypeScript types.

Get a key

In the console, open API and copy the Agent key. It belongs to one agent, and every call made with it is recorded as that agent’s. The key proves the identity, so you can leave out agentId.

export INVOKE_API_KEY=inv_live_…

The Account key also works. It can act for any agent registered in your workspace, so name the agent with agentId on each call, or set INVOKE_AGENT_ID. Keep keys on the server. Never ship one to a browser.

Variable
`INVOKE_API_KEY`	Required. An agent key (recommended) or your account key.
`INVOKE_API_URL`	Default `https://api.invokehq.run`
`INVOKE_WORKSPACE_ID`	Default: the one workspace the key can see
`INVOKE_AGENT_ID`	Default acting agent, for account keys

Invoke.fromEnv() reads these. To configure in code instead, use new Invoke({ apiKey, baseUrl, workspaceId, agentId, timeoutMs, maxRetries, fetch }).

invoke.call()

Field	Type
`tool`	`string`	Required. The tool to run, such as `linear.update_issue`.
`params`	`object`	The tool’s arguments.
`agentId`	`string`	Who is acting. With an agent key, the key decides.
`idempotencyKey`	`string`	Names the action. The same key is the same action: it runs at most once.
`intent`	`string`	Why the agent is doing it. Recorded on the receipt.
`waitForApproval`	`boolean \| { timeoutMs, pollMs }`	Wait for a human instead of throwing `ApprovalRequiredError`.

Before the tool runs, Invoke checks the agent’s identity and permissions, your workspace policies, the budget, and whether another agent has claimed the work item. Then it reserves the cost, runs the tool once, settles the cost and seals a receipt.

The result

call() resolves only for an action that happened:

{
  ok: true,
  status: "committed",          // or "duplicate": a repeat of a finished action, so nothing ran again
  output: { /* what the tool returned */ },
  receipt: {
    number: "#e59a65d7",
    verified: true,             // the ledger still matches what was signed
    sealedWith: "current",      // which key signed it
    raw: { /* who, why, input, output, cost, approval */ },
  },
  effectId: "eff_e59a65d78a5a4baf941fefaa",
  agentId: "coding-agent",
  costUsd: 0.001,
  durationMs: 291,
}

Idempotency

Name every action that must not happen twice. The same idempotencyKey means the same action. It could be sent again by your retry loop, a worker that crashed and restarted, or an agent re-running its plan. Either way it runs once, and every repeat gets the original receipt with status: "duplicate". Build the key from what makes the action unique, such as invoice:${invoiceId}, DRA-8:done or webhook:${event.id}. Reusing a key with different params is refused with idempotency_conflict, because one key names one action. Without a key, the SDK makes one for each call, so its own network retries are still safe. But if your code calls again, that’s a new action.

Errors

Every failure is an InvokeError. Its class tells you whether the action happened:

Error	Did it happen?	What to do
`DeniedError`	No	`err.decision` names the check that refused it: `denied_permission`, `denied_policy`, `denied_budget`, `denied_identity`, `denied_claim`, `idempotency_conflict`, `unknown_tool` or `unknown_agent`.
`ApprovalRequiredError`	Not yet	A policy wants a human. Approve it in the console, or pass `waitForApproval`.
`ToolError`	No	The tool failed and nothing changed. Fix the input and call again.
`OutcomeUnknownError`	Maybe	The tool got the request but its answer was lost. See below.
`ConnectionError`	Only if it reached Invoke	The SDK already retried with the same key. Call again later with the same `idempotencyKey`.
`ConfigError`	No	A setup problem. The message says what to set.

import { ApprovalRequiredError, DeniedError, OutcomeUnknownError } from "@invokehq/sdk"

try {
  await invoke.call({ tool, params, idempotencyKey })
} catch (err) {
  if (err instanceof DeniedError) {
    // refused before anything ran; err.decision says which check
  } else if (err instanceof ApprovalRequiredError) {
    // waiting for a human; nothing has run yet
  } else if (err instanceof OutcomeUnknownError) {
    // it may have happened; retry only if err.safeToRetry
  } else {
    throw err
  }
}

When the outcome is unknown

Sometimes the request reaches the tool and the answer never comes back. Invoke doesn’t guess what happened.

Tools that are safe to re-run as the same action, such as reads and linear.update_issue, are reconciled for you: the SDK sends the same action again. You only see OutcomeUnknownError if that fails too.
Anything else, such as a charge or an email, could act twice if retried. Invoke holds the action as unknown and sets err.safeToRetry to false. Someone checks the real system and settles it at err.resolveUrl. happened commits the action and seals its receipt. not_happened releases the budget so an honest retry can run.

Approvals

Approvals come from workspace policies. For example, “stripe.charge_customer over 5000 needs a human” (created with an account key):

curl -X POST https://api.invokehq.run/v1/workspaces/$WORKSPACE_ID/policies \
  -H "X-API-Key: $ACCOUNT_KEY" -H "Content-Type: application/json" \
  -d '{"name": "big charges need a human", "effect": "require_approval",
       "match": {"tool": "stripe.charge_customer"},
       "conditions": [{"field": "amount", "op": "gt", "value": 5000}]}'

A call that matches throws ApprovalRequiredError, and nothing runs. To wait for the decision instead, which by default waits up to 10 minutes:

const done = await invoke.call({
  tool: "stripe.charge_customer",
  params: { customer_id: "cus_123", amount: 50_000, currency: "usd", invoice_id: "inv_881" },
  idempotencyKey: "invoice:inv_881",
  waitForApproval: { timeoutMs: 300_000 },
})

Once approved, the action runs and call() resolves with its receipt, which records who approved it. If the reviewer rejects it, call() throws DeniedError.

Before and after

await invoke.preview({ tool, params })  // { allowed, verdict, reason }: would it run? Runs nothing.
await invoke.receipt(done)              // the full receipt
await invoke.trace(done)                // the run, stage by stage: agent → identity → task → context →
                                        // policy → budget → action → result → receipt
invoke.agent("billing-agent")           // the same client, acting as another agent (account keys)

Next steps

Quick Start: your first call in five minutes
How It Works: what Invoke checks before an action runs
Environment Variables: every setting the SDK reads

Get Started

Core Concepts

Guides

SDK & CLI

Configuration

TypeScript SDK

Install

Get a key

invoke.call()

The result

Idempotency

Errors

When the outcome is unknown

Approvals

Before and after

Next steps

​Install

​Get a key

​invoke.call()

​The result

​Idempotency

​Errors

​When the outcome is unknown

​Approvals

​Before and after

​Next steps

Install

Get a key

invoke.call()

The result

Idempotency

Errors

When the outcome is unknown

Approvals

Before and after

Next steps