AI Workforce OneHQDocs

TypeScript SDK

The HQ API for TypeScript and JavaScript, with retries, idempotency, a resumable event stream and webhook verification built in.

Not published yet

The package is not on npm yet; this page shows how it will work. Until it is, call the API with fetch as in the quickstart.

@aiworkforceoneofficial/hq-sdk runs on Node 20+, Deno, Bun and workers, with no runtime dependencies.

npm install @aiworkforceoneofficial/hq-sdk

Authenticate

import { HQ } from '@aiworkforceoneofficial/hq-sdk';

const hq = new HQ({ apiKey: process.env.HQ_API_KEY });

apiKey takes an API key or an OAuth app's access token. Without it, the SDK reads HQ_API_KEY. Each client pins the HQ-Version the SDK was built for; pass apiVersion to pin another.

Send a prompt and stream the reply

const session = await hq.sessions.create('team_3kQ9…', { engine: 'claude', run_with: 'team_key' });
await hq.sessions.messages.create(session.id!, {
  content: [{ type: 'text', text: 'Summarise open PRs in /data/repo' }],
});
for await (const ev of hq.sessions.stream(session.id!)) {
  if (ev.type === 'session.message.completed') console.log(ev.data);
  if (ev.type === 'session.turn.completed') break;
}

What it does for you

Retries. A 429, a 5xx or a dropped connection is retried with backoff (maxRetries, default 2), honouring Retry-After. A 421 is retried once at once. Any other 4xx is thrown at once.

Idempotency. Every write carries an Idempotency-Key, the same one across its own retries, so a retry never sends a prompt twice or resizes a machine twice. Pass { idempotencyKey } to use yours.

Errors. A refusal throws an HQError with the stable code, the status, the detail and the requestId:

import { HQError } from '@aiworkforceoneofficial/hq-sdk';

try {
  await hq.sessions.create('team_3kQ9…', { run_with: 'team_key' });
} catch (err) {
  if (err instanceof HQError && err.code === 'permission_denied') console.log(err.permission);
  else throw err;
}

Streaming. sessions.stream(id) yields each event once, resumes with Last-Event-ID across stream.rotate and dropped connections, and yields stream.reset when you should re-list the session's items. Pass { signal } to stop it.

Operations. A Cloud Computer change answers an operation; operations.wait(op) polls it until it settles, honouring Retry-After:

const op = await hq.computer.resize('team_3kQ9…', { tier: 'boost' });
if (op.object === 'operation') await hq.operations.wait(op);

Pagination. teams.list() and sessions.list() are async iterators over every page.

Webhooks. Verify a delivery with the raw body:

const event = await HQ.webhooks.verify(rawBody, req.headers, process.env.HQ_WEBHOOK_SECRET!);

Everything else. hq.call('operationId', { path_param: '…' }, { query, body }) reaches any endpoint in the reference, and every schema is exported as a type.