Object reference

Fields are camelCase. Optional fields that are null are left out of responses.

BotProfile

Field	Type
id	string	Stable id
name, job	string
askMeFor	string	What other bots can hand it
instructions	string
modelKey	string	A key from GET /models
effort	string	Quick, Balanced, Deep or Max
color	int	Its colour: an index into the avatar palette
body	string	Its blot shape
worksIn	string	Auto, Browser, Computer or ThisPc
canBrowse	bool	May use the built-in browser
memoryEnabled, memoryAutoLearn	bool	Long-term memory, and learning facts by itself
skillDrafting	bool	Drafts skills from its work
plugins	string[] or null	Plugin ids it may use; null means every connected plugin
skills	string[]	Skill names it uses
logins	string[]	Login ids it may use
quillSites, blotterSites	string[]	Site ids it works on
blotterAgentIds	object	Read-only: its agent id on each Blotter site
isGroup	bool	A group chat
members	string[]	A group's bot ids
chiefId	string	A group's coordinator
isChief	bool	The team's Chief of Staff
goal	object	Read-only here; set with PUT /bots/{id}/goal
created, updated	date

BotConversation

Field
profile	BotProfile
messages	SavedMessage[], oldest first
runningTurnId	The turn running now, if any
pendingApprovals	ApprovalPrompt[] waiting for an answer
pendingQuestions	QuestionPrompt[] waiting for an answer
context	{ usedTokens, windowTokens, condensedMessages, modelName, measured }
pendingHandoffs	Hand-offs whose results will come back here

SavedMessage

Field
id	Stable id
fromUser	true for your messages (and messages other bots sent this one)
text	The text
at	When it was sent
attachments	{ name, mediaType, kind, fileName, size }[] (fetch with GET /bots/{id}/attachments/{fileName})
work	A reply's work log: { seconds, stopped, steps: [{ kind, title, detail, succeeded, summary }] }
metrics	A reply's tokens, timing and cost: modelName, inputTokens, cachedInputTokens, outputTokens, reasoningTokens, requests, totalSeconds, firstTokenSeconds, costUsd, estimated…
changes	Files the reply changed: { path, status, added, removed, undone }[]
pinned	Pinned
replyToId, replyExcerpt, replyAuthor	The message it replies to
authorId, authorName	In a group chat, the member who wrote it
isNotice	An error or "stopped" note that's never sent to the model
routineId, routineName	Sent by a routine
triggerId, triggerName, triggerPayload	Started by a webhook

ApprovalPrompt

Field
id	Answer with POST /approvals/{id}
kind	Read, Edit, Execute, Network, App or Other
title, detail	What it wants to do
modelReason	Why, in the model's words
outsideWorkspace	Paths outside the workspace
commandPattern	What AllowCommand would add to the allowlist
scope	Set for computer hand-overs

QuestionPrompt

{
  "id": "q-7f2…",
  "botName": "Scout",
  "at": "2026-10-30T14:05:00+00:00",
  "questions": [
    {
      "question": "Which database should the report use?",
      "header": "Database",
      "multiple": false,
      "options": [ { "label": "PostgreSQL", "description": "Production, read-only" }, { "label": "SQLite" } ]
    }
  ]
}

ProviderState

id, name, tagline, kind, auth (ApiKey, ServerUrl, ServerUrlAndKey, ChatGptSignIn, AgentCli or Managed), connected, accountLabel, baseUrl, models ({ id, name, enabled, contextTokens }[]), agentInstalled, agentManagesAccounts, canSignInHere.

PluginState

id, name, tagline, description, category, isCustom, transport, url, command, args, envKeys and headerKeys (names only), auth, usesOAuth, hasSavedKey, connected, accountLabel, lastError, tools ({ name, title, description, readOnly, enabled }[]) and, for Composio, connectedApps.

Routine

id, name, botId, instructions, enabled, schedule, time, days, dayOfMonth, everyMinutes, at, timeLimitMinutes, continuity, and, read-only, created, lastRun, lastStatus, runCount, nextRun and summary.

Trigger

id, name, botId, instructions, enabled, events, and, read-only, created, lastFired, lastStatus, fireCount and url.

Incident

id, kind, botId, botName, conversationId (the chat to open), source (routine, handoff or goal) and sourceId, what, error, created, resolvedAt, resolution, notes.

UsageRow

date, botId, botName, modelName, replies, requests, inputTokens, cachedInputTokens, outputTokens, costUsd, estimatedReplies.