ObjectStackObjectStack

Ai Answer schema — API Protocol reference

The AI answer follow-up routes: saved questions, an answer turned into an artifact, and an answer's rating.

The AI answer follow-up routes: saved questions, an answer turned into an artifact, and an answer's rating.

MethodPathRequestdata on success
GET/api/v1/ai/saved-questionsnoneListAiSavedQuestionsResponseSchema
POST/api/v1/ai/saved-questions[CreateAiSavedQuestionResponseSchema](CreateAiSavedQuestionRequestSchema) (201)
DELETE/api/v1/ai/saved-questions/:idnoneno body (204)
POST/api/v1/ai/saved-questions/:id/runnoneRunAiSavedQuestionResponseSchema
POST/api/v1/ai/conversations/:id/turns/:turnId/artifact[CreateAiAnswerArtifactResponseSchema](CreateAiAnswerArtifactRequestSchema) (201)
GET/api/v1/ai/conversations/:id/turns/:turnId/feedbacknoneGetAiAnswerFeedbackResponseSchema
POST/api/v1/ai/conversations/:id/turns/:turnId/feedback[SetAiAnswerFeedbackResponseSchema](SetAiAnswerFeedbackRequestSchema)
DELETE/api/v1/ai/conversations/:id/turns/:turnId/feedbacknoneno body (204), also when no rating was there

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/runtime domains/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.

Source: packages/spec/src/api/ai-answer.zod.ts

TypeScript Usage

import { AiAnswerArtifactDraftSchema, AiAnswerArtifactErrorSchema, AiAnswerArtifactErrorCodeSchema, AiAnswerArtifactKindSchema, AiAnswerArtifactRefusalReasonSchema, AiAnswerFeedbackSchema, AiAnswerFeedbackErrorSchema, AiAnswerFeedbackErrorCodeSchema, AiAnswerRatingSchema, AiSavedQuestionSchema, AiSavedQuestionErrorSchema, AiSavedQuestionErrorCodeSchema, AiSavedQuestionRefusalReasonSchema, CreateAiAnswerArtifactRequestSchema, CreateAiAnswerArtifactResponseSchema, CreateAiSavedQuestionRequestSchema, CreateAiSavedQuestionResponseSchema, GetAiAnswerFeedbackResponseSchema, ListAiSavedQuestionsResponseSchema, RunAiSavedQuestionResponseSchema, SetAiAnswerFeedbackRequestSchema, SetAiAnswerFeedbackResponseSchema } from '@objectstack/spec/api';
import type { AiAnswerArtifactDraft, AiAnswerArtifactError, AiAnswerArtifactErrorCode, AiAnswerArtifactKind, AiAnswerArtifactRefusalReason, AiAnswerFeedback, AiAnswerFeedbackError, AiAnswerFeedbackErrorCode, AiAnswerRating, AiSavedQuestion, AiSavedQuestionError, AiSavedQuestionErrorCode, AiSavedQuestionRefusalReason, CreateAiAnswerArtifactRequest, CreateAiAnswerArtifactResponse, CreateAiSavedQuestionRequest, CreateAiSavedQuestionResponse, GetAiAnswerFeedbackResponse, ListAiSavedQuestionsResponse, RunAiSavedQuestionResponse, SetAiAnswerFeedbackRequest, SetAiAnswerFeedbackResponse } from '@objectstack/spec/api';

// Validate data
const result = AiAnswerArtifactDraftSchema.parse(data);

AiAnswerArtifactDraft

Properties

PropertyTypeRequiredDescription
typeEnum<'dataset' | 'report' | 'dashboard'>✅Metadata type of the draft
namestring✅Metadata item name of the draft

AiAnswerArtifactError

Properties

PropertyTypeRequiredDescription
codeEnum<'UNAUTHENTICATED' | 'PERMISSION_DENIED' | 'MISSING_REQUIRED_FIELD' | 'VALIDATION_ERROR' | 'RESOURCE_NOT_FOUND' | 'NOT_IMPLEMENTED' | 'INTERNAL_ERROR' | … +1 more>✅Error code
declaredCodestringoptionalThe 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)
messagestring✅Readable error message
userMessagestringoptionalProducer-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.
refusaltrueoptionalProducer-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.
categorystringoptionalError category (e.g. validation, authorization)
httpStatusintegeroptionalHTTP status of the response carrying this error
details{ reason: Enum<'report_authoring_requires_manage_metadata' | 'report_authoring_walled' | …>; issues?: any }optionalPresent on a named refusal
requestIdstringoptionalRequest ID for tracking

Allowed Values: AiAnswerArtifactError.code

  • UNAUTHENTICATED
  • PERMISSION_DENIED
  • MISSING_REQUIRED_FIELD
  • VALIDATION_ERROR
  • RESOURCE_NOT_FOUND
  • NOT_IMPLEMENTED
  • INTERNAL_ERROR
  • SERVICE_UNAVAILABLE

Nested Shape: AiAnswerArtifactError.details

PropertyTypeRequiredDescription
reasonEnum<'report_authoring_requires_manage_metadata' | 'report_authoring_walled' | …>✅The named refusal
issuesanyoptionalThe schema issues, on spec_refused

AiAnswerArtifactErrorCode

Allowed Values

  • UNAUTHENTICATED
  • PERMISSION_DENIED
  • MISSING_REQUIRED_FIELD
  • VALIDATION_ERROR
  • RESOURCE_NOT_FOUND
  • NOT_IMPLEMENTED
  • INTERNAL_ERROR
  • SERVICE_UNAVAILABLE

AiAnswerArtifactKind

Allowed Values

  • view
  • report
  • widget

AiAnswerArtifactRefusalReason

Allowed Values

  • report_authoring_requires_manage_metadata
  • report_authoring_walled
  • answer_has_no_query
  • not_an_aggregate
  • not_a_record_list
  • filter_not_expressible
  • sort_not_expressible
  • limit_not_expressible
  • latest_per_not_expressible
  • member_not_expressible
  • spec_refused

AiAnswerFeedback

Properties

PropertyTypeRequiredDescription
conversationIdstring✅The conversation of the rated answer
turnIdstring✅The turn of the rated answer
ratingEnum<'up' | 'down'>✅The rating
notestring | null✅The caller's note; null when none
createdAtstring✅Creation timestamp (ISO 8601)
updatedAtstring | null✅Last change timestamp (ISO 8601); null when never set

AiAnswerFeedbackError

Properties

PropertyTypeRequiredDescription
codeEnum<'UNAUTHENTICATED' | 'PERMISSION_DENIED' | 'MISSING_REQUIRED_FIELD' | 'VALIDATION_ERROR' | 'VALUE_TOO_LONG' | 'RESOURCE_NOT_FOUND' | 'INTERNAL_ERROR' | … +2 more>✅Error code
declaredCodestringoptionalThe 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)
messagestring✅Readable error message
userMessagestringoptionalProducer-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.
refusaltrueoptionalProducer-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.
categorystringoptionalError category (e.g. validation, authorization)
httpStatusintegeroptionalHTTP status of the response carrying this error
detailsanyoptionalAdditional error context (e.g. field validation errors)
requestIdstringoptionalRequest ID for tracking

Allowed Values: AiAnswerFeedbackError.code

  • UNAUTHENTICATED
  • PERMISSION_DENIED
  • MISSING_REQUIRED_FIELD
  • VALIDATION_ERROR
  • VALUE_TOO_LONG
  • RESOURCE_NOT_FOUND
  • INTERNAL_ERROR
  • NOT_IMPLEMENTED
  • SERVICE_UNAVAILABLE

AiAnswerFeedbackErrorCode

Allowed Values

  • UNAUTHENTICATED
  • PERMISSION_DENIED
  • MISSING_REQUIRED_FIELD
  • VALIDATION_ERROR
  • VALUE_TOO_LONG
  • RESOURCE_NOT_FOUND
  • INTERNAL_ERROR
  • NOT_IMPLEMENTED
  • SERVICE_UNAVAILABLE

AiAnswerRating

Allowed Values

  • up
  • down

AiSavedQuestion

Properties

PropertyTypeRequiredDescription
idstring✅Saved question id
questionstring✅The question text
source{ object: string; label?: string; filter?: any; scope: Enum<'visible_to_you' | 'all_records'>; … } | null✅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
agentIdstring | null✅The agent of the conversation it was saved from; null for a typed question
conversationIdstring | null✅The conversation it was saved from; null for a typed question
turnIdstring | null✅The turn it was saved from; null for a typed question
createdAtstring✅Creation timestamp (ISO 8601)

Nested Shape: AiSavedQuestion.source

PropertyTypeRequiredDescription
objectstring✅The machine name of the object the figures were read from
labelstringoptionalThe 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
filteranyoptionalThe 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
scopeEnum<'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
groupBystring[]optionalThe field names the figures were grouped by, in order
aggregations{ function: Enum<'count' | 'sum' | 'avg' | 'min' | 'max' | 'count_distinct'>; field?: string }[]optionalThe aggregations computed, in order
orderBy{ field: string; order?: Enum<'asc' | 'desc'> }[]optionalThe ordering applied, in order of precedence
limitintegeroptionalThe row or group cut applied (a top-N read or a group cut). Present only together with orderBy
relatedstring[]optionalThe lookup paths read in the same call, dotted from the object (for example client.relationship_manager)
latestPer{ groupBy: string; orderField: string }optionalPresent when the answer keeps only the latest row per group
recordsintegeroptionalHow 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
linestring✅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

AiSavedQuestionError

Properties

PropertyTypeRequiredDescription
codeEnum<'UNAUTHENTICATED' | 'PERMISSION_DENIED' | 'MISSING_REQUIRED_FIELD' | 'VALIDATION_ERROR' | 'VALUE_TOO_LONG' | 'RESOURCE_NOT_FOUND' | 'RESOURCE_CONFLICT' | … +3 more>✅Error code
declaredCodestringoptionalThe 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)
messagestring✅Readable error message
userMessagestringoptionalProducer-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.
refusaltrueoptionalProducer-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.
categorystringoptionalError category (e.g. validation, authorization)
httpStatusintegeroptionalHTTP status of the response carrying this error
details{ reason: Enum<'saved_question_has_no_query' | 'saved_question_run_failed'>; question?: string }optionalPresent on a run refusal
requestIdstringoptionalRequest ID for tracking

Allowed Values: AiSavedQuestionError.code

  • UNAUTHENTICATED
  • PERMISSION_DENIED
  • MISSING_REQUIRED_FIELD
  • VALIDATION_ERROR
  • VALUE_TOO_LONG
  • RESOURCE_NOT_FOUND
  • RESOURCE_CONFLICT
  • INTERNAL_ERROR
  • NOT_IMPLEMENTED
  • SERVICE_UNAVAILABLE

Nested Shape: AiSavedQuestionError.details

PropertyTypeRequiredDescription
reasonEnum<'saved_question_has_no_query' | 'saved_question_run_failed'>✅The named refusal
questionstringoptionalThe saved question text, on saved_question_has_no_query

AiSavedQuestionErrorCode

Allowed Values

  • UNAUTHENTICATED
  • PERMISSION_DENIED
  • MISSING_REQUIRED_FIELD
  • VALIDATION_ERROR
  • VALUE_TOO_LONG
  • RESOURCE_NOT_FOUND
  • RESOURCE_CONFLICT
  • INTERNAL_ERROR
  • NOT_IMPLEMENTED
  • SERVICE_UNAVAILABLE

AiSavedQuestionRefusalReason

Allowed Values

  • saved_question_has_no_query
  • saved_question_run_failed

CreateAiAnswerArtifactRequest

Properties

PropertyTypeRequiredDescription
kindEnum<'view' | 'report' | 'widget'>✅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
toolCallIdstringoptionalThe tool call of the turn to build from; the turn's last query when omitted
labelstringoptionalThe artifact label; the turn's question when omitted. Cut to 120 characters

CreateAiAnswerArtifactResponse

Union Options

This schema accepts one of the following structures:

Option 1

Properties

PropertyTypeRequiredDescription
kind'view'✅The artifact kind
view{ id?: string; object_name: string; label: string; config: Record<string, any> }✅The saved personal view

Nested Shape: CreateAiAnswerArtifactResponse[kind='view'].view

PropertyTypeRequiredDescription
idstringoptionalThe personal view row id, when the engine answered one
object_namestring✅The object the view lists
labelstring✅The view label
configRecord<string, any>✅The list view configuration, a ListView

Option 2

Properties

PropertyTypeRequiredDescription
kind'report'✅The artifact kind
publishedfalse✅Always false: the drafts are not published
drafts{ type: Enum<'dataset' | 'report' | 'dashboard'>; name: string }[]✅The drafts staged: the dataset, then the report
datasetRecord<string, any>✅The dataset draft body
reportRecord<string, any>✅The report draft body

Nested Shape: CreateAiAnswerArtifactResponse[kind='report'].drafts[number]

PropertyTypeRequiredDescription
typeEnum<'dataset' | 'report' | 'dashboard'>✅Metadata type of the draft
namestring✅Metadata item name of the draft

Option 3

Properties

PropertyTypeRequiredDescription
kind'widget'✅The artifact kind
publishedfalse✅Always false: the drafts are not published
drafts{ type: Enum<'dataset' | 'report' | 'dashboard'>; name: string }[]✅The drafts staged: the dataset, then the dashboard
datasetRecord<string, any>✅The dataset draft body
dashboardRecord<string, any>✅The dashboard draft body

Nested Shape: CreateAiAnswerArtifactResponse[kind='widget'].drafts[number]

PropertyTypeRequiredDescription
typeEnum<'dataset' | 'report' | 'dashboard'>✅Metadata type of the draft
namestring✅Metadata item name of the draft


CreateAiSavedQuestionRequest

Properties

PropertyTypeRequiredDescription
questionstringoptionalThe 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)
conversationIdstringoptionalThe caller's conversation the answer is in; sent with turnId
turnIdstringoptionalThe turn of that conversation; sent with conversationId
toolCallIdstringoptionalThe tool call of the turn whose query is saved; the turn's last query when omitted

CreateAiSavedQuestionResponse

Properties

PropertyTypeRequiredDescription
question{ id: string; question: string; source: object | null; agentId: string | null; … }✅The saved question

Nested Shape: CreateAiSavedQuestionResponse.question

PropertyTypeRequiredDescription
idstring✅Saved question id
questionstring✅The question text
source{ object: string; label?: string; filter?: any; scope: Enum<'visible_to_you' | 'all_records'>; … } | null✅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
agentIdstring | null✅The agent of the conversation it was saved from; null for a typed question
conversationIdstring | null✅The conversation it was saved from; null for a typed question
turnIdstring | null✅The turn it was saved from; null for a typed question
createdAtstring✅Creation timestamp (ISO 8601)

GetAiAnswerFeedbackResponse

Properties

PropertyTypeRequiredDescription
feedback{ conversationId: string; turnId: string; rating: Enum<'up' | 'down'>; note: string | null; … } | null✅The caller's rating of the answer; null when unrated

Nested Shape: GetAiAnswerFeedbackResponse.feedback

PropertyTypeRequiredDescription
conversationIdstring✅The conversation of the rated answer
turnIdstring✅The turn of the rated answer
ratingEnum<'up' | 'down'>✅The rating
notestring | null✅The caller's note; null when none
createdAtstring✅Creation timestamp (ISO 8601)
updatedAtstring | null✅Last change timestamp (ISO 8601); null when never set

ListAiSavedQuestionsResponse

Properties

PropertyTypeRequiredDescription
questions{ id: string; question: string; source: object | null; agentId: string | null; … }[]✅The caller's saved questions in the session's organization, newest first, at most 200

Nested Shape: ListAiSavedQuestionsResponse.questions[number]

PropertyTypeRequiredDescription
idstring✅Saved question id
questionstring✅The question text
source{ object: string; label?: string; filter?: any; scope: Enum<'visible_to_you' | 'all_records'>; … } | null✅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
agentIdstring | null✅The agent of the conversation it was saved from; null for a typed question
conversationIdstring | null✅The conversation it was saved from; null for a typed question
turnIdstring | null✅The turn it was saved from; null for a typed question
createdAtstring✅Creation timestamp (ISO 8601)

RunAiSavedQuestionResponse

Properties

PropertyTypeRequiredDescription
questionstring✅The saved question text
toolNameEnum<'aggregate_data' | 'query_records'>✅The data tool that ran the query: aggregate_data for an aggregate, query_records for a record read
resultany✅The data tool's result, parsed from its JSON text

SetAiAnswerFeedbackRequest

Properties

PropertyTypeRequiredDescription
ratingEnum<'up' | 'down'>✅The rating
notestring | nulloptionalA note on the answer. Trimmed; blank or null stores none. A note longer than 500 characters is refused (413 VALUE_TOO_LONG)

SetAiAnswerFeedbackResponse

Properties

PropertyTypeRequiredDescription
feedback{ conversationId: string; turnId: string; rating: Enum<'up' | 'down'>; note: string | null; … }✅The stored rating

Nested Shape: SetAiAnswerFeedbackResponse.feedback

PropertyTypeRequiredDescription
conversationIdstring✅The conversation of the rated answer
turnIdstring✅The turn of the rated answer
ratingEnum<'up' | 'down'>✅The rating
notestring | null✅The caller's note; null when none
createdAtstring✅Creation timestamp (ISO 8601)
updatedAtstring | null✅Last change timestamp (ISO 8601); null when never set

On this page

TypeScript UsageAiAnswerArtifactDraftPropertiesAiAnswerArtifactErrorPropertiesAllowed Values: AiAnswerArtifactError.codeNested Shape: AiAnswerArtifactError.detailsAiAnswerArtifactErrorCodeAllowed ValuesAiAnswerArtifactKindAllowed ValuesAiAnswerArtifactRefusalReasonAllowed ValuesAiAnswerFeedbackPropertiesAiAnswerFeedbackErrorPropertiesAllowed Values: AiAnswerFeedbackError.codeAiAnswerFeedbackErrorCodeAllowed ValuesAiAnswerRatingAllowed ValuesAiSavedQuestionPropertiesNested Shape: AiSavedQuestion.sourceAiSavedQuestionErrorPropertiesAllowed Values: AiSavedQuestionError.codeNested Shape: AiSavedQuestionError.detailsAiSavedQuestionErrorCodeAllowed ValuesAiSavedQuestionRefusalReasonAllowed ValuesCreateAiAnswerArtifactRequestPropertiesCreateAiAnswerArtifactResponseUnion OptionsOption 1PropertiesNested Shape: CreateAiAnswerArtifactResponse[kind='view'].viewOption 2PropertiesNested Shape: CreateAiAnswerArtifactResponse[kind='report'].drafts[number]Option 3PropertiesNested Shape: CreateAiAnswerArtifactResponse[kind='widget'].drafts[number]CreateAiSavedQuestionRequestPropertiesCreateAiSavedQuestionResponsePropertiesNested Shape: CreateAiSavedQuestionResponse.questionGetAiAnswerFeedbackResponsePropertiesNested Shape: GetAiAnswerFeedbackResponse.feedbackListAiSavedQuestionsResponsePropertiesNested Shape: ListAiSavedQuestionsResponse.questions[number]RunAiSavedQuestionResponsePropertiesSetAiAnswerFeedbackRequestPropertiesSetAiAnswerFeedbackResponsePropertiesNested Shape: SetAiAnswerFeedbackResponse.feedback