User Hub API: schemas
The request and response bodies of the operations in this API.
ApprovalKindPayloadDto
| Property | Type | Required | Description |
|---|
allowRevise | boolean | yes | |
suggestedRejectReasons | array of string | yes | |
BulkUpsertPreferencesDto
ChoiceKindPayloadDto
DeviceResponseDto
| Property | Type | Required | Description |
|---|
channel | string | yes | |
createdAt | string | yes | |
deviceId | string | yes | |
id | string | yes | |
lastSeenAt | string | yes | |
metadata | object | yes | |
orgId | string | yes | |
updatedAt | string | yes | |
userId | string | yes | |
DeviceResponseDtoDataArrayEnvelope
DeviceResponseDtoDataEnvelope
| Property | Type | Required | Description |
|---|
maxLength | number or null | yes | |
placeholder | string or null | yes | |
NotificationActionContextDto
| Property | Type | Required | Description |
|---|
gateId | string | no | |
gateRequestId | string | no | |
page | one of "pipeline", "gates", "reviews", "work", "qa", "code", "settings" | no | |
phaseId | string | no | |
pipelineRunId | string | no | |
projectId | string | no | |
qaResultId | string | no | |
reviewId | string | no | |
workId | string | no | |
workItemId | string | no | |
NotificationAggregateType
Type: one of "inquiry", "workflow_run", "decision", "none"
NotificationCategory
Type: string (10 values)
NotificationChannel
Type: one of "web", "email"
NotificationChannelAvailability
Whether this channel can deliver in this deployment (not_configured: no transport provisioned)
Type: one of "available", "not_configured"
NotificationItemResponseDto
| Property | Type | Required | Description |
|---|
actionContext | NotificationActionContextDto | no | |
aggregateId | string or null | no | Aggregate id (e.g. inquiryId) when aggregateType !== none. |
aggregateType | NotificationAggregateType | yes | |
category | NotificationCategory | yes | |
channel | NotificationChannel | yes | |
createdAt | string (date-time) | yes | |
detail | string or null | no | |
eventType | string | yes | |
expiresAt | string (date-time) or null | no | Server-side TTL — past this instant the row auto-EXPIREs. |
groupKey | string or null | no | |
groupSeq | number or null | no | |
id | string | yes | |
metadata | NotificationMetadataDto | yes | |
occurredAt | string (date-time) | yes | |
projectId | string or null | no | |
publisher | NotificationPublisherDto or null | no | The authenticated publisher of an announcement, stamped by the platform. Null for rows that are not announcements or were created before publishers were recorded. |
readAt | string (date-time) or null | no | |
seenAt | string (date-time) or null | no | When the user last "saw" the row in the bell dropdown — distinct from readAt (item opened). |
severity | NotificationSeverity | yes | |
status | NotificationStatus | yes | Lifecycle state. Actionable rows are PENDING / RESPONDED; INFO is terminal-on-arrival. |
title | string | yes | |
version | number | yes | Optimistic-concurrency version. Bumped on every status update; clients keep max(version) to tolerate out-of-order frames. |
NotificationItemResponseDtoPaginatedEnvelope
| Property | Type | Required | Description |
|---|
actorName | string | no | |
branchName | string | no | |
checkKey | string | no | |
gateRequestId | string | no | |
phase | string | no | |
phaseName | string | no | |
pipelineId | string | no | |
pipelineRunId | string | no | |
prNumber | number | no | |
prTitle | string | no | |
projectName | string | no | |
reviewId | string | no | |
status | string | no | |
workItemId | string | no | |
NotificationMutationResponseDto
| Property | Type | Required | Description |
|---|
updatedCount | number | yes | Number of notifications that transitioned |
NotificationMutationResponseDtoDataEnvelope
NotificationPreferenceItemDto
| Property | Type | Required | Description |
|---|
category | string | yes | |
channel | string | yes | |
enabled | boolean | yes | |
minSeverity | string | no | |
NotificationPreferenceResponseDto
| Property | Type | Required | Description |
|---|
availability | NotificationChannelAvailability | yes | Whether this channel can deliver in this deployment (not_configured: no transport provisioned) |
category | string | yes | |
channel | string | yes | |
enabled | boolean | yes | |
isDefault | boolean | yes | Whether this is a code-level default or an explicit override |
minSeverity | string | yes | |
NotificationPreferenceResponseDtoDataArrayEnvelope
NotificationPreferenceResponseDtoDataEnvelope
NotificationPublisherDto
NotificationPublisherKind
Type: one of "service", "user"
NotificationSeverity
Type: one of "INFO", "SUCCESS", "WARNING", "ACTION_REQUIRED", "ERROR"
NotificationStatus
Lifecycle state. Actionable rows are PENDING / RESPONDED; INFO is terminal-on-arrival.
Type: one of "pending", "responded", "resolved", "cancelled", "expired", "info"
| Property | Type | Required | Description |
|---|
hasMore | boolean | no | |
limit | number | no | |
nextCursor | string or null | no | |
page | number | no | |
previousCursor | string or null | no | |
total | number | no | |
totalPages | number | no | |
PreferenceResponseDto
| Property | Type | Required | Description |
|---|
key | string | yes | Preference key |
scope | one of "global", "project" | yes | |
scopeId | object or null | no | |
updatedAt | string | yes | |
value | object | yes | Preference value (any JSON-serializable value) |
PreferenceResponseDtoDataArrayEnvelope
PreferenceResponseDtoDataEnvelope
ProblemActionableBy
Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed.
Type: one of "user", "org-admin", "platform", "none"
ProblemDetailsDto
RFC 9457 problem document. The declared members are the reserved core; extension members are TOP-LEVEL and OPEN, owned by the refusing plane.
| Property | Type | Required | Description |
|---|
actionableBy | ProblemActionableBy | no | Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed. |
code | string | yes | SCREAMING_SNAKE_CASE. The machine-branchable refusal, and the value a policy rule, a retry predicate and a UI branch all name. |
detail | string | no | Human-readable and specific to THIS occurrence. |
errors | array of ProblemFieldIssueDto | no | Field-level issues, when the refusal is about the request body. |
instance | string | no | URI reference identifying the occurrence — a request path, a run, a row. |
params | map of string or number or boolean | no | Safe i18n interpolation values for the message keyed by code — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics. |
retry | ProblemRetry | no | What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known. |
status | number | yes | The HTTP status code, repeated in the body so a logged document is self-contained. |
title | string | yes | Short, human-readable, and STABLE for a given type. Never per-occurrence — that is detail. |
traceId | string | no | W3C trace-context trace-id, present when the caller sent a traceparent. Omitted rather than invented when it did not. |
type | string | yes | Absolute URI identifying the refusal TYPE. Derived one-to-one from code, so a caller may branch on either and can never be told two different things. Never about:blank. |
ProblemFieldIssueDto
| Property | Type | Required | Description |
|---|
code | string | no | SCREAMING_SNAKE_CASE code of THIS issue, for a frontend i18n key. Present when the issue was minted by a declared problem. |
detail | string | yes | Prose for logs and developers. A frontend localises from code + params instead. |
params | map of string or number or boolean | no | Safe i18n interpolation values for this issue's code. |
pointer | string | yes | RFC 6901 JSON Pointer into the request body. Root is "/". |
ProblemRetry
What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known.
Type: one of "transient", "after-change", "never"
QuestionActionContextDto
| Property | Type | Required | Description |
|---|
runId | string | yes | |
stageKey | string or null | yes | |
taskAnchor | string | yes | |
workflowSlug | string | yes | |
QuestionBadgeResponseDto
| Property | Type | Required | Description |
|---|
count | number | yes | Total pending questions for the current user across all runs. |
QuestionBadgeResponseDtoDataEnvelope
QuestionChoiceOptionDto
| Property | Type | Required | Description |
|---|
description | string or null | yes | |
label | string | yes | |
value | string | yes | |
QuestionEscalationLevelDto
| Property | Type | Required | Description |
|---|
enteredAt | string (date-time) | yes | |
expired | boolean | yes | |
expiredAt | string (date-time) or null | yes | |
level | number | yes | |
recipientDisplayName | string | yes | |
QuestionKind
Type: one of "approval", "choice", "freeform", "review"
QuestionKindPayloadDto
QuestionResponseDto
| Property | Type | Required | Description |
|---|
action | QuestionActionContextDto | yes | |
description | string or null | yes | Long-form markdown context. Distinct from detail (one-liner under the title) — projected from the inquiry prompt's description. |
detail | string or null | yes | |
escalationHistory | array of QuestionEscalationLevelDto | yes | |
expiresAt | string (date-time) or null | yes | |
extras | object | yes | Closed-set orchestrator render hints (reviewIteration, reviewerFindings[], pastIterations[], reviewSubjects[]). |
id | string | yes | |
kind | QuestionKind | yes | |
kindPayload | QuestionKindPayloadDto | yes | |
occurredAt | string (date-time) | yes | |
recipientId | string | yes | Engine-side InquiryRecipient.id PK for THIS recipient. Required by the FE reply-submit call. Empty string for legacy rows that pre-date the wiring. |
severity | QuestionSeverity | yes | |
status | QuestionStatus | yes | |
subjects | array of QuestionSubjectRefDto | yes | |
title | string | yes | |
QuestionResponseDtoPaginatedEnvelope
QuestionSeverity
Type: one of "urgent", "normal", "info"
QuestionStatus
Type: one of "pending", "responded", "resolved", "expired", "cancelled"
QuestionSubjectRefDto
| Property | Type | Required | Description |
|---|
artifactId | string | yes | |
kind | string | no | |
title | string | no | |
version | number | yes | |
versionId | string | yes | Immutable per-version handle as stored on the artifact-store ArtifactVersion row. Required so the FE can build proper W3C Web Annotation targets (ReviewInquiryCommentSchema.anchor) without synthesising a placeholder from (artifactId, version). |
RegisterDeviceDto
| Property | Type | Required | Description |
|---|
channel | string | yes | Delivery channel |
deviceId | string | yes | Client-generated device identifier |
metadata | object | no | Additional device metadata |
ReviewKindPayloadDto
| Property | Type | Required | Description |
|---|
allowAnchor | boolean | yes | |
placeholder | string or null | yes | |
SetPreferenceItemDto
| Property | Type | Required | Description |
|---|
key | string | yes | Preference key, e.g. "schema:action-menu-mode" |
scope | one of "global", "project" | no | |
scopeId | string | no | Scope qualifier — e.g. projectId when scope=project |
value | object | yes | Preference value (any JSON-serializable value, including null) |
SetPreferencesDto
SinglePreferenceDto
| Property | Type | Required | Description |
|---|
enabled | boolean | yes | |
minSeverity | string | no | |
SyncConflictItemDto
| Property | Type | Required | Description |
|---|
clientUpdatedAt | string | yes | |
clientValue | object | yes | Client-side value that was overridden |
key | string | yes | |
scope | one of "global", "project" | yes | |
scopeId | object or null | no | |
serverUpdatedAt | string | yes | |
serverValue | object | yes | Server-side value that won |
SyncPreferenceItemDto
| Property | Type | Required | Description |
|---|
key | string | yes | Preference key, e.g. "schema:action-menu-mode" |
scope | one of "global", "project" | no | |
scopeId | string | no | Scope qualifier — e.g. projectId when scope=project |
updatedAt | string | yes | Client-side updatedAt for conflict resolution (ISO string) |
value | object | yes | Preference value (any JSON-serializable value, including null) |
SyncPreferencesDto
SyncResponseDto
SyncResponseDtoDataEnvelope
UnreadResponseDto
| Property | Type | Required | Description |
|---|
byCategory | object | yes | |
highestSeverity | NotificationSeverity or null | no | |
unreadCount | number | yes | |
UnreadResponseDtoDataEnvelope