SDK

SDK API reference

A complete overview of the client’s constructor, methods and helpers.

new AistAgentClient(options)

Option	Type	Purpose
`baseUrl`	string	The AIST Agent gateway URL.
`token`	string	The JWT for the `Authorization: Bearer` header.
`headers?`	object	Extra headers sent with every request.
`timeoutMs?`	number	Timeout for a single HTTP request (`0` — no timeout).
`fetch?`	function	A custom `fetch` (tests / Node < 18).

Low-level methods

These map one-to-one to the API endpoints.

Method	Endpoint
`getMe(signal?)`	`GET /api/me` → `AccountInfo`: token expiry, limits, task counters. Since 0.4.0
`listAssistants(signal?)`	`GET /api/assistants` → `AssistantSummary[]` — `id` is the `assistant_id`; hidden assistants aren’t listed (see Assistants). Since 0.4.0
`getAssistant(slug, signal?)`	`GET /api/assistants/{slug}` → `AssistantDetails` with `models` — `models[].id` is the `llm_model_id`; an unavailable one throws `NotFoundError`. Since 0.4.0
`createTask(input, signal?)`	`POST /api/tasks` → `{ uuid, status, max_execution_time }`. `input` may include `max_execution_time` — the execution limit in seconds (see Creating a task)
`listTasks(query?, signal?)`	`GET /api/tasks` → `{ data: TaskSummary[], meta }`. `query.status` — a status or an array of statuses, `query.page`, `query.perPage`
`getTask(uuid, signal?)`	`GET /api/tasks/{uuid}` → `Task`
`submitToolResults(uuid, results, signal?)`	`POST /api/tasks/{uuid}/tool-results`
`cancelTask(uuid, opts?)`	`POST /api/tasks/{uuid}/cancel` → `{ uuid, status: 'canceled' }`. `opts.reason` — the reason (up to 1000 characters)
`cancelInterruptedTasks(opts?)`	`POST /api/tasks/cancel-interrupted` → `{ canceled, uuids }` — cancels all interrupted tasks at once
`uploadFile(file, opts?)`	`POST /api/files` → an input-ready object
`getStorageBase(signal?)`	`GET /api/storage/base` → `string`

High-level helpers

waitForTask(uuid, opts?)

Polls the task until its status lands in stopOn (default: completed/failed/canceled/interrupted).

Option	Purpose
`pollIntervalMs`	Polling interval. Default 1500.
`timeoutMs`	Overall wait timeout (`0` — no timeout).
`stopOn`	Statuses at which waiting stops.
`onPoll`	Callback after every poll.
`signal`	`AbortSignal` for cancellation.

runTask(input, opts?)

Creates a task and runs the client tool interrupt cycle automatically until a terminal status. Options are on the runTask and client tools page.

textInput / fileInput / voiceInput

Helper functions that build input items with the correct type.

textInput('Hello')                     // { type: 'text', text: 'Hello' }
fileInput({ id: '42', name: 'a.pdf', mime_type: 'application/pdf' })
voiceInput({ id: '7', name: 'v.ogg', mime_type: 'audio/ogg' })

Key types

Type	Description
`TaskStatus`	`'pending' \| 'processing' \| 'interrupted' \| 'completed' \| 'failed' \| 'canceled'`
`Task`	The `GET /api/tasks/{uuid}` response: `uuid, status, turn, error, …`
`Turn`	`output, messages, metadata, interrupt?`
`InputItem`	`TextInputItem \| FileInputItem \| VoiceInputItem`
`PendingToolCall`	`{ id, name, arguments }` — a call pending while `interrupted`
`AccountInfo`	The `getMe` response: `user_id, token { expires_at, abilities }, limits { max_active_tasks, max_execution_time }, tasks { active, total, by_status, last_created_at }, storage_url`
`AssistantSummary`	A `listAssistants` row: `id, slug, title, description, avatar_url, owned, categories`
`AssistantDetails`	The `getAssistant` response: assistant fields + `models: AssistantModel[]` (`id, label, description, is_default, features`) and `options`
`TaskSummary`	A `listTasks` row: `uuid, status, error, created_at, completed_at, pending_tool_calls?` (no `turn`)