Like the other /api/v1/ai/** shapes in protocol.zod.ts, these describe
the wire, not a protocol this repo serves: the producer is the cloud AI
service (service-ai: routes/saved-question-routes.ts,
routes/feedback-routes.ts, saved/saved-question-store.ts,
saved/source-artifact.ts, feedback/answer-feedback-store.ts). Every
success body is the platform envelope { success: true, data } and each
response schema here is the data payload. A failure body is
{ success: false, error } with error one of the three route errors below,
whose code lists hold both the route handler's codes and the framework
door's. The door answers ahead of the handler, with no details: 401
UNAUTHENTICATED for a caller with no session (packages/runtimedomains/ai.ts; a route mounted on the HTTP server answers the flat
{ error, code, message } body instead, dispatcher-plugin.ts, ADR-0112),
501 NOT_IMPLEMENTED when the deployment serves no AI, and 503
SERVICE_UNAVAILABLE before the AI routes are published.
Every route is the signed-in caller's own: a saved question that is not the
caller's answers 404, and a conversation that is not the caller's answers 403
when a question is saved from one of its answers, and on the artifact and
feedback routes.
The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message
string
✅
Readable error message
userMessage
string
optional
Producer-marked user-facing refusal text, verbatim, in the request's locale: platform-composed text falls back to the workspace default locale, then en; an app-authored refusal falls back to its declared wording. Present exactly when the producer opted in at throw time; consumers render it to end users as received and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal
true
optional
Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category
string
optional
Error category (e.g. validation, authorization)
httpStatus
integer
optional
HTTP status of the response carrying this error
details
{ reason: Enum<'report_authoring_requires_manage_metadata' | 'report_authoring_walled' | …>; issues?: any }
The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message
string
✅
Readable error message
userMessage
string
optional
Producer-marked user-facing refusal text, verbatim, in the request's locale: platform-composed text falls back to the workspace default locale, then en; an app-authored refusal falls back to its declared wording. Present exactly when the producer opted in at throw time; consumers render it to end users as received and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal
true
optional
Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category
string
optional
Error category (e.g. validation, authorization)
httpStatus
integer
optional
HTTP status of the response carrying this error
details
any
optional
Additional error context (e.g. field validation errors)
The query the answer ran, read off the caller's stored turn when the question was saved from an answer; null for a typed question, or when the answer ran no query
agentId
string | null
✅
The agent of the conversation it was saved from; null for a typed question
conversationId
string | null
✅
The conversation it was saved from; null for a typed question
turnId
string | null
✅
The turn it was saved from; null for a typed question
The machine name of the object the figures were read from
label
string
optional
The object's plural label, or its label when it declares no plural. Translated only when the request is in Chinese and a zh* translation pack names the object; otherwise the authored label, not the caller's UI locale. Absent when the producer sets none: a reader falls back to object
filter
any
optional
The caller's where, in the $ query dialect, exactly as the engine accepted it: machine names only, no field labels, date placeholders such as {today} as written. Absent when no condition applied
scope
Enum<'visible_to_you' | 'all_records'>
✅
The row scope the figures cover, judged by the producer per call from ISecurityService.getReadFilter(object, ctx) for this caller and object, under the same context the read ran under. visible_to_you: a row restriction applied, so the figures cover only the records the caller may read. The organization wall is a row restriction: under the isolated and group tenancy postures getReadFilter answers an organization_id predicate on every object that carries the column, for every caller but a platform admin whose object's posture lets them cross the wall, so an organization owner there reads visible_to_you. all_records: stated only when that call RESOLVED to undefined, so no row restriction applied; for a caller no row rule or sharing narrows, that is the single posture, an object outside tenancy, a platform admin crossing the wall, or a system context. An absent security service, an absent getReadFilter, a call that throws or rejects, or a call made under any other context than the read's own states visible_to_you. A restriction applied is the fact stated, not a count of rows excluded. The value speaks for object only, not for the objects behind related lookup paths. Always present, one of these two values
groupBy
string[]
optional
The field names the figures were grouped by, in order
The row or group cut applied (a top-N read or a group cut). Present only together with orderBy
related
string[]
optional
The lookup paths read in the same call, dotted from the object (for example client.relationship_manager)
latestPer
{ groupBy: string; orderField: string }
optional
Present when the answer keeps only the latest row per group
records
integer
optional
How many records the figures cover — a count, never a list: the match total for a page read, the summed group counts for an aggregate or a chart, 1 for get_record. Absent when unknown, never guessed
line
string
✅
The finished one-line citation, in the request language. The producer keeps it to at most 280 characters; a reader does not refuse a longer one
The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message
string
✅
Readable error message
userMessage
string
optional
Producer-marked user-facing refusal text, verbatim, in the request's locale: platform-composed text falls back to the workspace default locale, then en; an app-authored refusal falls back to its declared wording. Present exactly when the producer opted in at throw time; consumers render it to end users as received and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal
true
optional
Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
view: the caller's own list view; report: a dataset and a report draft; widget: a dataset and a new one-widget dashboard draft. report and widget need the manage_metadata capability
toolCallId
string
optional
The tool call of the turn to build from; the turn's last query when omitted
label
string
optional
The artifact label; the turn's question when omitted. Cut to 120 characters
The question text. Required without conversationId; from an answer it replaces the turn's own question. A question longer than 2000 characters is refused (413 VALUE_TOO_LONG)
conversationId
string
optional
The caller's conversation the answer is in; sent with turnId
turnId
string
optional
The turn of that conversation; sent with conversationId
toolCallId
string
optional
The tool call of the turn whose query is saved; the turn's last query when omitted
The query the answer ran, read off the caller's stored turn when the question was saved from an answer; null for a typed question, or when the answer ran no query
agentId
string | null
✅
The agent of the conversation it was saved from; null for a typed question
conversationId
string | null
✅
The conversation it was saved from; null for a typed question
turnId
string | null
✅
The turn it was saved from; null for a typed question
The query the answer ran, read off the caller's stored turn when the question was saved from an answer; null for a typed question, or when the answer ran no query
agentId
string | null
✅
The agent of the conversation it was saved from; null for a typed question
conversationId
string | null
✅
The conversation it was saved from; null for a typed question
turnId
string | null
✅
The turn it was saved from; null for a typed question