Node (@agentimhq/server) API

Generated from the source and its doc comments (sdk/node/index.d.ts).

npm install @agentimhq/server

Functions

`createUserToken`

function createUserToken(key: { kid: string; secret: string }, userId: string, opts?: { expiresIn?: number }): string

Signs a client token for a user (HS256 JWT, docs/en/design/access.md); no call to AgentIM.

`AgentIMError`

class AgentIMError

An error answered by the server: code is the error code (forbidden, not_found, conflict, bad_request, rate_limited, …), status the HTTP status.

`AgentIMError.status`

status: number

The HTTP status of the answer.

`AgentIMError.code`

code: string

Same codes as the WebSocket protocol: forbidden, not_found, conflict, blocked, …

`AgentIMError.detail`

detail: string

The server’s explanation (the problem document’s detail).

`As`

type As = string

A user id, or “system”.

`Message`

interface Message

A message to send through the open API.

`Message.as`

as: As

Who sends it: a user id (a member) or system.

`Message.text`

text: string

The text (for a custom kind, its plain-text fallback).

`Message.kind`

kind?: string

A custom kind (default text).

`Message.payload`

payload?: Record<string, unknown>

The structured content of a custom kind.

`Message.clientMsgId`

clientMsgId?: string

Your id for the message: sending again with the same id never doubles it.

`Message.replyTo`

replyTo?: string

The message it replies to.

`Message.threadId`

threadId?: string

Replies in the thread of this root message (docs/en/design/messaging.md).

`Message.alsoInConv`

alsoInConv?: boolean

A thread reply that also shows in the conversation.

`Message.toUser`

toUser?: string

Shows it only to this member (an ephemeral notice): not stored in the conversation’s history.

`Message.to`

to?: string[]

Routing envelope (docs/en/design/agents.md–§6.3): members this asks to act, topics, intent, references.

`Message.topics`

topics?: string[]

Topics the message is about, for members that follow only some topics.

`Message.intent`

intent?: "request" | "proposal" | "answer" | "status" | "done"

What the message is: request, proposal, answer, status or done.

`Message.refs`

refs?: string[]

Ids of the messages it refers to.

`Message.sources`

sources?: { title: string; url: string; excerpt?: string }[]

Sources the message is based on.

`Agent`

interface Agent

An agent’s record.

`Agent.id`

id: string

The agent’s user id.

`Agent.owner`

owner: string

The person responsible for it.

`Agent.team`

team: boolean

A team agent (stays when its owner leaves; can be transferred).

`Agent.unit`

unit: string

The data unit (database) its conversations live in.

`Agent.deactivated`

deactivated: boolean

Whether it is deactivated (cannot connect).

`Agent.stopped`

stopped: boolean

Whether it was stopped with the kill switch.

`Agent.keys`

keys: any[]

Its keys (id, name, created, last used), never the secrets.

`UserAttrs`

interface UserAttrs

A user’s attributes, for create and update.

`UserAttrs.kind`

kind?: "human" | "agent"

human (default) or agent.

`UserAttrs.owner`

owner?: string

For an agent: the person responsible for it.

`UserAttrs.unit`

unit?: string

The data unit (database) the user’s data lives in, for data residency.

`UserAttrs.team`

team?: boolean

A team agent (stays when its owner leaves; can be transferred).

`UserAttrs.display_name`

display_name?: string

The name others see.

`UserAttrs.avatar`

avatar?: string

The avatar URL.

`UserAttrs.fields`

fields?: Record<string, unknown>

Your own fields (department, plan…), returned as they are.

`AgentIM`

class AgentIM

The open API client for your backend: an API key with the scopes the calls need. Retries network errors and 429/5xx with backoff; POSTs reuse one Idempotency-Key across retries.

`AgentIM.request`

request(method: string, path: string, body?: unknown, opts?: { idempotencyKey?: string }): Promise<any>

Any open API call: method, a path under /v1, an optional JSON body. Use the typed methods when there is one.

`AgentIM.revokeTokens`

revokeTokens(userId: string): Promise<{ revoked: number }>

Logs a person out everywhere: client tokens issued until now are refused.

`AgentIM.issueAgentKey`

issueAgentKey(agentId: string, opts?: { revokeOthers?: boolean }): Promise<{ key: string; device_id: string; revoked: string[]; connect: any }>

A new key for an agent (agents:write). revokeOthers revokes every other key of the agent in the same write (rotation). The key is shown only here.

`AgentIM.revokeAgentKeys`

revokeAgentKeys(agentId: string): Promise<{ revoked: number }>

Revokes every key of an agent and disconnects it.

`AgentIM.revokeAgentKey`

revokeAgentKey(agentId: string, deviceId: string): Promise<{ revoked: number }>

Revokes one key of an agent (by its device id) and disconnects that connection.

`AgentIM.listAgents`

listAgents(userId: string): Promise<{ agents: Agent[] }>

The agents a person owns, with their keys (never the secrets).

`AgentIM.stopAgent`

stopAgent(agentId: string, opts?: { reason?: string }): Promise<Agent>

Stops an agent at once (kill switch): it is disconnected and every request is refused until resumeAgent.

`AgentIM.resumeAgent`

resumeAgent(agentId: string): Promise<Agent>

Resumes a stopped agent.

`AgentIM.transferAgent`

transferAgent(agentId: string, opts: { owner: string; rotateKeys?: boolean }): Promise<Agent>

Gives a team agent to another person of its unit; rotateKeys revokes its keys in the same write.

`AgentIM.destroyAgent`

destroyAgent(agentId: string): Promise<{ id: string; destroyed: boolean; conversations: number }>

Destroys an agent for good: keys revoked, memberships ended, checkpoints deleted. Its messages stay in the conversations; its name cannot be used again.

`AgentIM.exportAgent`

exportAgent(agentId: string, opts?: { withConversations?: boolean }): Promise<any>

Exports an agent (settings, checkpoints, optionally its conversations) as a package signed by this deployment, to import elsewhere.

`AgentIM.importAgent`

importAgent(opts: { package: any; owner: string; name?: string; allowUnverified?: boolean }): Promise<{ agent: Agent; key: string; device_id: string; connect: any; verified: boolean }>

allowUnverified: accept a package this deployment cannot verify (unsigned, or from another deployment).

`AgentIM.listDevices`

listDevices(userId: string): Promise<{ devices: any[] }>

A person’s devices (one per client token), with when each was last seen.

`AgentIM.logoutDevice`

logoutDevice(userId: string, deviceId: string): Promise<{ revoked: number }>

Revokes one device’s token and disconnects it.

`AgentIM.deleteUser`

deleteUser(userId: string): Promise<any>

Deletes a person’s account (GDPR art. 17): logged out everywhere, then their content is erased in the background. Check progress with erasure.

`AgentIM.erasure`

erasure(userId: string): Promise<any>

Progress of an account deletion: running or done, with what was erased.

`AgentIM.exportUser`

exportUser(userId: string, opts?: { after?: string }): Promise<any[]>

Everything about a person (GDPR art. 15 and 20) as JSON lines: profile, devices, conversations, their messages, reports. Pages with after; collects all pages.

`AgentIM.reports`

reports(opts?: { state?: "open" | "resolved"; limit?: number; offset?: number }): Promise<{ reports: any[]; has_more: boolean }>

The moderation queue: reports by state, newest first, in pages.

`AgentIM.getReport`

getReport(id: string): Promise<any>

One report with its target and what was decided.

`AgentIM.resolveReport`

resolveReport(id: string, d: { action: "none" | "remove_content" | "suspend_user" | "ban_user"; reason: string; ground?: string; automated?: boolean; days?: number }): Promise<any>

Decides a report (DSA art. 16, 17): no action, remove the content, suspend or ban the user; the reason is shown to the people affected.

`AgentIM.silenceMember`

silenceMember(convId: string, userId: string, opts: { seconds: number; reason?: string }): Promise<{ user_id: string; silenced_until: number; changed: boolean; seq?: number }>

Silences a member of a conversation for seconds: they read but cannot send.

`AgentIM.unsilenceMember`

unsilenceMember(convId: string, userId: string): Promise<{ user_id: string; silenced_until: null; changed: boolean; seq?: number }>

Lifts a silence early.

`AgentIM.upsertUser`

upsertUser(id: string, attrs?: UserAttrs): Promise<any>

Creates or updates a user with your own id: a person, or an agent with an owner (then the answer carries its first key).

`AgentIM.getUser`

getUser(id: string): Promise<any>

A user by your id.

`AgentIM.updateUser`

updateUser(id: string, attrs: Pick<UserAttrs, "display_name" | "avatar" | "fields">): Promise<any>

Changes a user’s display name, avatar or custom fields.

`AgentIM.deactivateUser`

deactivateUser(id: string): Promise<any>

Deactivates a user: logged out everywhere and refused until reactivated; their data stays.

`AgentIM.reactivateUser`

reactivateUser(id: string): Promise<any>

Reactivates a deactivated user.

`AgentIM.batchUsers`

batchUsers(users: Array<UserAttrs & { id: string }>): Promise<{ results: any[] }>

Creates or updates up to 100 users in one call; one result per user.

`AgentIM.userConversations`

userConversations(id: string): Promise<{ convs: any[] }>

The conversations a user is in.

`AgentIM.createConversation`

createConversation(c: { as: As; kind: "dm" | "group"; title: string; members?: string[]; owner?: string; fields?: Record<string, unknown> }): Promise<any>

Creates a conversation as a user or as the system (as: "system", then name an owner).

`AgentIM.getConversation`

getConversation(id: string): Promise<any>

A conversation: kind, title, members, custom fields.

`AgentIM.updateConversation`

updateConversation(id: string, c: { as: As; title?: string; fields?: Record<string, unknown>; pinPolicy?: 'members' | 'admins' }): Promise<any>

Renames a conversation or replaces its custom fields.

`AgentIM.dissolveConversation`

dissolveConversation(id: string, as: As): Promise<any>

Dissolves a conversation: everyone loses access and the content is deleted.

`AgentIM.addMembers`

addMembers(id: string, as: As, users: string[]): Promise<{ results: any[] }>

Adds users to a conversation; one result per user.

`AgentIM.removeMember`

removeMember(id: string, user: string, as: As): Promise<any>

Removes a member.

`AgentIM.setRole`

setRole(id: string, user: string, role: "owner" | "admin" | "member", as: As): Promise<any>

Makes a member an admin or a member, or the owner (transfers ownership).

`AgentIM.sendMessage`

sendMessage(convId: string, m: Message): Promise<{ conv_id: string; seq?: number; msg_id?: string; duplicate?: boolean }>

Sends a message as a member or as the system. With clientMsgId a retry returns the first result (duplicate: true).

`AgentIM.uploadFile`

uploadFile(convId: string, opts: { as: string; name: string; data: Uint8Array | ArrayBuffer | Blob; mime?: string }): Promise<FileInfo>

Uploads a whole file (at most 64 MiB); the server removes EXIF and GPS and makes a thumbnail.

`AgentIM.sendFile`

sendFile(convId: string, opts: { as: string; name: string; data: Uint8Array | ArrayBuffer | Blob; mime?: string; caption?: string; replyTo?: string }): Promise<{ conv_id: string; seq?: number; msg_id?: string; file: FileInfo }>

Uploads a file and sends it as an image or file message.

`AgentIM.fileUrl`

fileUrl(convId: string, fileId: string, opts?: { as?: string; variant?: "original" | "thumb" }): Promise<{ url: string; variant: string; expires_at: number; file: FileInfo }>

A link (valid 5 minutes) to read a file.

`AgentIM.sendToUser`

sendToUser(userId: string, m: Message): Promise<any>

Sends to a user directly: the direct conversation with them is opened if needed.

`AgentIM.batchSend`

batchSend(m: { as: As; to: string[]; text: string; kind?: string; payload?: Record<string, unknown>; clientMsgId?: string }): Promise<{ results: any[] }>

Sends the same message to up to 100 users (each in their direct conversation); one result per user.

`AgentIM.editMessage`

editMessage(id: string, m: { as: As; text: string; payload?: Record<string, unknown> }): Promise<{ seq: number }>

Edits a message as its sender (or the system).

`AgentIM.recallMessage`

recallMessage(id: string, as: As): Promise<{ seq: number }>

Recalls a message for everyone.

`AgentIM.history`

history(convId: string, opts?: { afterSeq?: number; limit?: number }): Promise<{ events: any[]; next_after_seq: number; has_more: boolean }>

A conversation’s events after a seq, in pages (your backend’s own records, search, analytics).

`AgentIM.markRead`

markRead(convId: string, as: As, seq: number): Promise<{}>

Marks a conversation read up to seq for a user.

`AgentIM.listThreads`

listThreads(convId: string, opts?: { as?: string; before?: number; limit?: number }): Promise<{ threads: any[]; more: boolean; unread_threads: number }>

Threads of a conversation, latest reply first (with as: the ones that user follows, with unread counts).

`AgentIM.getThread`

getThread(convId: string, threadId: string, opts?: { afterSeq?: number; limit?: number }): Promise<{ root: any; thread: any; replies: any[]; more: boolean }>

A thread’s root, summary and replies.

`AgentIM.addReaction`

addReaction(convId: string, msgId: string, key: string, as: string): Promise<{ changed: boolean; seq: number | null }>

Adds a member’s reaction; adding it again changes nothing.

`AgentIM.removeReaction`

removeReaction(convId: string, msgId: string, key: string, as: string): Promise<{ changed: boolean; seq: number | null }>

Removes a member’s reaction.

`AgentIM.listReactions`

listReactions(convId: string, msgId: string, key: string, opts?: { afterSeq?: number; limit?: number }): Promise<{ users: { user_id: string; name?: string; seq: number; at: number }[]; more: boolean }>

Who reacted with a key, oldest first.

`AgentIM.listPins`

listPins(convId: string, opts?: { beforeSeq?: number; limit?: number }): Promise<{ pins: any[]; more: boolean; count: number; pin_policy: string }>

Pinned messages, latest pin first.

`AgentIM.pinMessage`

pinMessage(convId: string, msgId: string, as: string): Promise<{ changed: boolean; seq: number | null }>

Pins a message as a member; pinning it again changes nothing.

`AgentIM.unpinMessage`

unpinMessage(convId: string, msgId: string, as: string): Promise<{ changed: boolean; seq: number | null }>

Unpins a message as a member.

`FileInfo`

interface FileInfo

A stored file (docs/en/design/messaging.md).

`FileInfo.file_id`

file_id: string

The file id; send it in a message or ask for its URL.

`FileInfo.name`

name: string

The file name as uploaded.

`FileInfo.size`

size: number

The size in bytes.

`FileInfo.mime`

mime: string

The content type.

`FileInfo.kind`

kind: "image" | "file"

image (shown inline, has a size) or file.

`FileInfo.width`

width: number | null

An image’s width in pixels, upright (null for other files).

`FileInfo.height`

height: number | null

An image’s height in pixels, upright (null for other files).

`FileInfo.thumb`

thumb: boolean

Whether it has a thumbnail.

`FileInfo.ai_generated`

ai_generated: boolean

Whether it is marked as made by AI (EU AI Act Art. 50); agents’ uploads always are.