Nurama Developers
Namespaces

bot

Methods and types of the `bot` namespace (`client.bot` / `bot.bot`).

Interfaces

Bot

Properties

PropertyTypeDescription
accountType"bot"-
apiKey?BotApiKeySummary-
apiKeys?BotApiKeySummary[]-
avatar?anyPopulated avatar Asset (joined server-side from avatarId). The web client resolves the image URL from this field via getAvatarUrl().
avatarIdstring | null-
colorstring-
createdAtstring-
displayNamestring-
idstring-
membershipId?string-
projectMemberships?BotProjectMembership[]Project memberships within the workspace the bot belongs to. Populated by listBots and getBot. Empty array if the bot has no project assignments.
roles?string[]-
statusstring-
updatedAtstring-

BotApiKeySummary

Properties

PropertyTypeDescription
createdAtstring-
expiresAt?string | null-
idstring-
keyPrefixstring-
kind?"botAccess" | "pat" | "oauthAccess" | "oauthRefresh" | nullDiscriminator. Bot keys mint as 'botAccess'.
lastUsed?string | null-
namestring-
scopes?string[]Granted scopes. A bot key is minted with the full registry when none are chosen.
status"active" | "revoked"-

BotProjectMembership

Properties

PropertyType
membershipIdstring
projectIdstring
projectNamestring
rolesBotProjectRole[]

CreateBotData

Properties

PropertyTypeDescription
color?stringOptional hex color from the approved palette. Auto-assigned if omitted.
namestringDisplay name for the bot. 1–50 characters.
roles("workspaceAdmin" | "workspaceMember" | "workspaceChatMember")[]Workspace roles to grant the bot. Must be one or more of: workspaceAdmin, workspaceMember, workspaceChatMember.
scopes?string[]Optional API-key scopes. Omit (or pass an empty array) to mint the key with the full scope registry, which is what the bot's roles already allow — every route declares a scope now, so a genuinely empty set would leave the key unable to call anything. Pass a subset to narrow it.

CreateBotKeyData

Properties

PropertyTypeDescription
expiresAt?stringOptional expiry, ISO 8601. Must be in the future.
namestringLabel shown in the bot's key list.
scopes?string[]Validated server-side against the token-scope registry. Omit for the full set.

CreateBotKeyResponse

Properties

PropertyTypeDescription
apiKeyBotApiKeySummary-
rawKeystringRaw API key. Returned once and not recoverable afterwards.

CreateBotResponse

Properties

PropertyTypeDescription
botBot-
rawKeystringRaw API key, returned ONCE at creation time. Store it immediately — it cannot be retrieved again.

RotateBotKeyResponse

Properties

PropertyTypeDescription
apiKeyBotApiKeySummary-
rawKeystringNew raw API key. Returned once.

UpdateBotAvatarFileData

Properties

PropertyType
checksumstring
namestring
sizeInMBnumber

UpdateBotAvatarResponse

Indexable

[k: string]: unknown

Properties

PropertyType
asset?{ [k: string]: unknown; id: string; }
asset.idstring
signedUrlData?{ key: string; uploadId: string; urls: string[]; }
signedUrlData.keystring
signedUrlData.uploadIdstring
signedUrlData.urlsstring[]
user{ avatarId: string | null; id: string; }
user.avatarIdstring | null
user.idstring

UpdateBotData

Properties

PropertyType
color?string
name?string

UpdateBotKeyScopesData

Properties

PropertyTypeDescription
scopesstring[]The COMPLETE new scope set, not a delta — the same shape createBotKey takes. At least one scope; a scopeless key authenticates and is then refused by every gated route, so revoke it instead of emptying it.

Type Aliases

BotProjectRole

type BotProjectRole = "creator" | "reviewer" | "projectAdmin";

Functions

default()

function default(client): {
  createBot: Promise<CreateBotResponse>;
  createBotKey: Promise<CreateBotKeyResponse>;
  deleteBot: Promise<void>;
  getBot: Promise<Bot>;
  listBots: Promise<Bot[]>;
  listProjectMemberships: Promise<BotProjectMembership[]>;
  removeProjectMembership: Promise<void>;
  revokeBotKey: Promise<void>;
  rotateBotKey: Promise<RotateBotKeyResponse>;
  setProjectMembership: Promise<BotProjectMembership>;
  updateBot: Promise<Bot>;
  updateBotAvatar: Promise<UpdateBotAvatarResponse>;
  updateBotKeyScopes: Promise<BotApiKeySummary>;
};

Bot user administration methods. Used by workspace owners/admins (callers holding a JWT) to manage bot users in a workspace. Bots themselves cannot call these endpoints — bot administration is restricted server-side.

Parameters

ParameterType
clientdefault

Returns

NameTypeDescription
createBot()(workspaceId, data) => Promise<CreateBotResponse>Create a bot user in a workspace. Returns the new bot and the raw API key (shown only once).
createBotKey()( workspaceId, botId, keyData ) => Promise<CreateBotKeyResponse>Mint an ADDITIONAL API key for the bot, up to 5 live keys. Unlike rotateBotKey, the bot's existing keys keep working — which is what makes a zero-downtime changeover possible: mint, move traffic over, then revoke the old key. The raw key is returned once.
deleteBot()(workspaceId, botId) => Promise<void>Delete a bot user. Revokes all API keys, removes the workspace membership, and marks the user inactive.
getBot()(workspaceId, botId) => Promise<Bot>Get a single bot's details, including all of its API key metadata (no secrets).
listBots()(workspaceId) => Promise<Bot[]>List bot users in a workspace.
listProjectMemberships()(workspaceId, botId) => Promise<BotProjectMembership[]>List the bot's project memberships within the workspace.
removeProjectMembership()( workspaceId, botId, projectId ) => Promise<void>Remove the bot's membership on a project. Idempotent.
revokeBotKey()( workspaceId, botId, keyId ) => Promise<void>Revoke one of the bot's API keys, leaving its others working. A revoked key stops authenticating immediately and frees a slot against the 5-key cap.
rotateBotKey()(workspaceId, botId) => Promise<RotateBotKeyResponse>Revoke the bot's current API key and issue a new one. The new raw key is returned once. The replacement carries the old key's scopes verbatim, so this is not a way to pick up scopes added to the registry since the key was minted — updateBotKeyScopes is.
setProjectMembership()( workspaceId, botId, projectId, data ) => Promise<BotProjectMembership>Upsert the bot's membership on a project. Replaces roles if a membership already exists; creates one otherwise. Idempotent.
updateBot()( workspaceId, botId, data ) => Promise<Bot>Update a bot's display name and/or color.
updateBotAvatar()( workspaceId, botId, fileData ) => Promise<UpdateBotAvatarResponse>Request signed URL data to upload a new avatar for the bot. Caller multipart-uploads the file to S3 using the returned signedUrlData, then calls client.asset.completeUpload(...) to finalize.
updateBotKeyScopes()( workspaceId, botId, keyId, data ) => Promise<BotApiKeySummary>Replace the scopes on one of the bot's API keys, in place. A key's scopes are a snapshot taken when it was minted, and the registry grows — a key created before a scope existed cannot hold it. Rotation is not a substitute: rotateBotKey copies the old scope set onto the replacement, so a stale key stays stale through every rotation. This matters most for keys minted with scopes omitted, which means "the full registry" as it stood that day, not "whatever the full registry becomes". The secret is unchanged — every caller configured with this key keeps working, which is the whole point. Requires canManageBots.

On this page