objectstack/content/docs/references/api/protocol.mdx at 12323caa8659de78da9f655691c90145a56a27b0 · objectstack-ai/objectstack

title	Protocol
description	Protocol protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

Response for GET /api/v1/automation/actions (ADR-0018).

Returns the live action/node registry — the platform's built-in actions plus

any plugin-contributed ones — backing the designer palette and flow

validation. Each entry is a canonical ActionDescriptorSchema.

**Source:** `packages/spec/src/api/protocol.zod.ts`

TypeScript Usage

import { AiInsightsRequest, AiInsightsResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, AutomationActionsResponse, AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CheckPermissionRequest, CheckPermissionResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, CreateViewRequest, CreateViewResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, DeleteMetaItemRequest, DeleteMetaItemResponse, DeleteViewRequest, DeleteViewResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetEffectivePermissionsRequest, GetEffectivePermissionsResponse, GetFieldLabelsRequest, GetFieldLabelsResponse, GetLocalesRequest, GetLocalesResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetNotificationPreferencesRequest, GetNotificationPreferencesResponse, GetObjectPermissionsRequest, GetObjectPermissionsResponse, GetPresenceRequest, GetPresenceResponse, GetTranslationsRequest, GetTranslationsResponse, GetUiViewRequest, GetUiViewResponse, GetViewRequest, GetViewResponse, GetWorkflowConfigRequest, GetWorkflowConfigResponse, GetWorkflowStateRequest, GetWorkflowStateResponse, HttpFindQueryParams, ListNotificationsRequest, ListNotificationsResponse, ListViewsRequest, ListViewsResponse, MarkAllNotificationsReadRequest, MarkAllNotificationsReadResponse, MarkNotificationsReadRequest, MarkNotificationsReadResponse, NotificationPreferences, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeDisconnectRequest, RealtimeDisconnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, RealtimeUnsubscribeRequest, RealtimeUnsubscribeResponse, RegisterDeviceRequest, RegisterDeviceResponse, SaveMetaItemRequest, SaveMetaItemResponse, SetPresenceRequest, SetPresenceResponse, UnregisterDeviceRequest, UnregisterDeviceResponse, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, UpdateViewRequest, UpdateViewResponse, WorkflowState, WorkflowTransitionRequest, WorkflowTransitionResponse } from '@objectstack/spec/api';
import type { AiInsightsRequest, AiInsightsResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, AutomationActionsResponse, AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CheckPermissionRequest, CheckPermissionResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, CreateViewRequest, CreateViewResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, DeleteMetaItemRequest, DeleteMetaItemResponse, DeleteViewRequest, DeleteViewResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetEffectivePermissionsRequest, GetEffectivePermissionsResponse, GetFieldLabelsRequest, GetFieldLabelsResponse, GetLocalesRequest, GetLocalesResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetNotificationPreferencesRequest, GetNotificationPreferencesResponse, GetObjectPermissionsRequest, GetObjectPermissionsResponse, GetPresenceRequest, GetPresenceResponse, GetTranslationsRequest, GetTranslationsResponse, GetUiViewRequest, GetUiViewResponse, GetViewRequest, GetViewResponse, GetWorkflowConfigRequest, GetWorkflowConfigResponse, GetWorkflowStateRequest, GetWorkflowStateResponse, HttpFindQueryParams, ListNotificationsRequest, ListNotificationsResponse, ListViewsRequest, ListViewsResponse, MarkAllNotificationsReadRequest, MarkAllNotificationsReadResponse, MarkNotificationsReadRequest, MarkNotificationsReadResponse, NotificationPreferences, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeDisconnectRequest, RealtimeDisconnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, RealtimeUnsubscribeRequest, RealtimeUnsubscribeResponse, RegisterDeviceRequest, RegisterDeviceResponse, SaveMetaItemRequest, SaveMetaItemResponse, SetPresenceRequest, SetPresenceResponse, UnregisterDeviceRequest, UnregisterDeviceResponse, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, UpdateViewRequest, UpdateViewResponse, WorkflowState, WorkflowTransitionRequest, WorkflowTransitionResponse } from '@objectstack/spec/api';

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

AiInsightsRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name to analyze
recordId	`string`	optional	Specific record to analyze
type	`Enum<'summary' \| 'trends' \| 'anomalies' \| 'recommendations'>`	optional	Type of insight

AiInsightsResponse

Properties

Property	Type	Required	Description
insights	`{ type: string; title: string; description: string; confidence?: number; … }[]`	✅	Generated insights

AiNlqRequest

Properties

Property	Type	Required	Description
query	`string`	✅	Natural language query string
object	`string`	optional	Target object context
conversationId	`string`	optional	Conversation ID for multi-turn queries

AiNlqResponse

Properties

Property	Type	Required	Description
query	`any`	✅	Generated structured query (AST)
explanation	`string`	optional	Human-readable explanation of the query
confidence	`number`	optional	Confidence score (0-1)
suggestions	`string[]`	optional	Suggested follow-up queries

AiSuggestRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name for context
field	`string`	optional	Field to suggest values for
recordId	`string`	optional	Record ID for context
partial	`string`	optional	Partial input for completion

AiSuggestResponse

Properties

Property	Type	Required	Description
suggestions	`{ value: any; label: string; confidence?: number; reason?: string }[]`	✅	Suggested values

AutomationActionsResponse

Properties

Property	Type	Required	Description
actions	`{ type: string; version: string; name: string; description?: string; … }[]`	✅	Registered action descriptors (built-in + plugin)
total	`integer`	✅	Number of descriptors returned (after any filters)

AutomationTriggerRequest

Properties

Property	Type	Required	Description
trigger	`string`	✅
payload	`Record<string, any>`	✅

AutomationTriggerResponse

Properties

Property	Type	Required
success	`boolean`	✅
jobId	`string`	optional
result	`any`	optional

BatchDataRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
request	`{ operation: Enum<'create' \| 'update' \| 'upsert' \| 'delete'>; records: { id?: string; data?: Record<string, any>; externalId?: string }[]; options?: object }`	✅	Batch operation request

BatchDataResponse

Properties

Property	Type	Required	Description
success	`boolean`	✅	Operation success status
error	`{ code: string; message: string; category?: string; details?: any; … }`	optional	Error details if success is false
meta	`{ timestamp: string; duration?: number; requestId?: string; traceId?: string }`	optional	Response metadata
operation	`Enum<'create' \| 'update' \| 'upsert' \| 'delete'>`	optional	Operation type that was performed
total	`number`	✅	Total number of records in the batch
succeeded	`number`	✅	Number of records that succeeded
failed	`number`	✅	Number of records that failed
results	`{ id?: string; success: boolean; errors?: { code: string; message: string; category?: string; details?: any; … }[]; data?: Record<string, any>; … }[]`	✅	Detailed results for each record

CheckPermissionRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name to check permissions for
action	`Enum<'create' \| 'read' \| 'edit' \| 'delete' \| 'transfer' \| 'restore' \| 'purge'>`	✅	Action to check
recordId	`string`	optional	Specific record ID (for record-level checks)
field	`string`	optional	Specific field name (for field-level checks)

CheckPermissionResponse

Properties

Property	Type	Required	Description
allowed	`boolean`	✅	Whether the action is permitted
reason	`string`	optional	Reason if denied

CreateDataRequest

Properties

Property	Type	Required	Description
object	`string`	✅	The object name.
data	`Record<string, any>`	✅	The dictionary of field values to insert.

CreateDataResponse

Properties

Property	Type	Required	Description
object	`string`	✅	The object name.
id	`string`	✅	The ID of the newly created record.
record	`Record<string, any>`	✅	The created record, including server-generated fields (created_at, owner).
droppedFields	`{ object: string; fields: string[]; reason: Enum<'readonly' \| 'readonly_when'> }[]`	optional	Write-observability (#3407/#3431): caller-supplied fields that were LEGALLY stripped before the record was written — a non-system create cannot seed a static `readonly` column (#3043 ingress strip), so those keys are dropped and the field re-derives its default. Present ONLY when ≥1 field was dropped; the create still succeeded without them (status/success semantics unchanged). REST additionally surfaces this as the `X-ObjectStack-Dropped-Fields` response header. Optional — omit-when-empty keeps the shape backward-compatible for existing clients.

CreateManyDataRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
records	`Record<string, any>[]`	✅	Array of records to create

CreateManyDataResponse

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
records	`Record<string, any>[]`	✅	Created records
count	`number`	✅	Number of records created
droppedFields	`{ object: string; fields: string[]; reason: Enum<'readonly' \| 'readonly_when'> }[]`	optional	Write-observability (#3407/#3431/#3455): caller-supplied `readonly` fields the #3043 create-ingress strip removed before the rows were written. AGGREGATED across the batch (one event per object/reason with the union of dropped field names) rather than per-row, because the insert-time strip is static-`readonly` only — schema-uniform, so every row drops the same set. Present ONLY when ≥1 field was dropped; the creates still succeeded without them (count/success unchanged). Optional — omit-when-empty keeps the shape backward-compatible. (The per-row `insertMany`/`batch` paths carry per-row `droppedFields` on each result instead — see BatchOperationResultSchema.)

CreateViewRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name (snake_case)
data	{ list?: object; form?: object; listViews?: Record<string, { name?: string; label?: string; type?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record<string, any> }; … }>; formViews?: Record<string, { type?: Enum<'simple' \| 'tabbed' \| 'wizard' \| 'split' \| 'drawer' \| 'modal'>; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }>; … }	✅	View definition to create

CreateViewResponse

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
viewId	`string`	✅	Created view identifier
view	{ list?: object; form?: object; listViews?: Record<string, { name?: string; label?: string; type?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record<string, any> }; … }>; formViews?: Record<string, { type?: Enum<'simple' \| 'tabbed' \| 'wizard' \| 'split' \| 'drawer' \| 'modal'>; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }>; … }	✅	Created view definition

DeleteDataRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
id	`string`	✅	Record ID to delete
expectedVersion	`string`	optional	Optimistic concurrency token (typically the `updated_at` value the client read). When provided, the server compares it against the current record version and returns 409 CONCURRENT_UPDATE if they differ. Optional — omit to skip the check.

DeleteDataResponse

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
id	`string`	✅	Deleted record ID
success	`boolean`	✅	Whether deletion succeeded

DeleteManyDataRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
ids	`string[]`	✅	Array of record IDs to delete
options	`{ atomic: boolean; returnRecords: boolean; continueOnError: boolean; validateOnly: boolean }`	optional	Delete options

DeleteManyDataResponse

Properties

Property	Type	Required	Description
success	`boolean`	✅	Operation success status
error	`{ code: string; message: string; category?: string; details?: any; … }`	optional	Error details if success is false
meta	`{ timestamp: string; duration?: number; requestId?: string; traceId?: string }`	optional	Response metadata
operation	`Enum<'create' \| 'update' \| 'upsert' \| 'delete'>`	optional	Operation type that was performed
total	`number`	✅	Total number of records in the batch
succeeded	`number`	✅	Number of records that succeeded
failed	`number`	✅	Number of records that failed
results	`{ id?: string; success: boolean; errors?: { code: string; message: string; category?: string; details?: any; … }[]; data?: Record<string, any>; … }[]`	✅	Detailed results for each record

DeleteMetaItemRequest

Properties

Property	Type	Required	Description
type	`string`	✅	Metadata type name
name	`string`	✅	Item name

DeleteMetaItemResponse

Properties

Property	Type	Required
success	`boolean`	✅
reset	`boolean`	optional
message	`string`	optional

DeleteViewRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name (snake_case)
viewId	`string`	✅	View identifier to delete

DeleteViewResponse

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
viewId	`string`	✅	Deleted view identifier
success	`boolean`	✅	Whether deletion succeeded

FindDataRequest

Properties

Property	Type	Required	Description
object	`string`	✅	The unique machine name of the object to query (e.g. "account").
query	`{ object: string; fields?: string \| { field: string; fields?: object[]; alias?: string }[]; where?: any; search?: object; … }`	optional	Structured query definition (filter, sort, select, pagination).

FindDataResponse

Properties

Property	Type	Required	Description
object	`string`	✅	The object name for the returned records.
records	`Record<string, any>[]`	✅	The list of matching records.
total	`number`	optional	Total number of records matching the filter (if requested).
nextCursor	`string`	optional	Cursor for the next page of results (cursor-based pagination).
hasMore	`boolean`	optional	True if there are more records available (pagination).

GetDataRequest

Properties

Property	Type	Required	Description
object	`string`	✅	The object name.
id	`string`	✅	The unique record identifier (primary key).
select	`string[]`	optional	Fields to include in the response (allowlisted query param).
expand	`string[]`	optional	Lookup/master_detail field names to expand. The engine resolves these via batch $in queries, replacing foreign key IDs with full objects.

GetDataResponse

Properties

Property	Type	Required	Description
object	`string`	✅	The object name.
id	`string`	✅	The record ID.
record	`Record<string, any>`	✅	The complete record data.

GetDiscoveryRequest

Properties

Property	Type	Required	Description

GetDiscoveryResponse

Properties

Property	Type	Required	Description
name	`string`	optional
version	`string`	✅
environment	`Enum<'production' \| 'sandbox' \| 'development'>`	optional
routes	`{ data: string; metadata: string; discovery?: string; ui?: string; … }`	optional
locale	`{ default: string; supported: string[]; timezone: string }`	optional
services	`Record<string, { enabled: boolean; status: Enum<'available' \| 'registered' \| 'unavailable' \| 'degraded' \| 'stub'>; handlerReady?: boolean; route?: string; … }>`	optional	Per-service availability map keyed by CoreServiceName
capabilities	`Record<string, { enabled: boolean; features?: Record<string, boolean>; description?: string }>`	optional	Hierarchical capability descriptors for frontend intelligent adaptation
schemaDiscovery	`{ openapi?: string; graphql?: string; jsonSchema?: string }`	optional	Schema discovery endpoints for API toolchain integration
metadata	`Record<string, any>`	optional	Custom metadata key-value pairs for extensibility
apiName	`string`	optional	API name (deprecated — use name)

GetEffectivePermissionsRequest

Properties

Property	Type	Required	Description

GetEffectivePermissionsResponse

Properties

Property	Type	Required	Description
objects	`Record<string, { allowCreate: boolean; allowRead: boolean; allowEdit: boolean; allowDelete: boolean; … }>`	✅	Effective object permissions keyed by object name
systemPermissions	`string[]`	✅	Effective system-level permissions

GetFieldLabelsRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
locale	`string`	✅	BCP-47 locale code

GetFieldLabelsResponse

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
locale	`string`	✅	Locale code
labels	`Record<string, { label: string; help?: string; options?: Record<string, string> }>`	✅	Field labels keyed by field name

GetLocalesRequest

Properties

Property	Type	Required	Description

GetLocalesResponse

Properties

Property	Type	Required	Description
locales	`{ code: string; label: string; isDefault: boolean }[]`	✅	Available locales

GetMetaItemCachedRequest

Properties

Property	Type	Required	Description
type	`string`	✅	Metadata type name
name	`string`	✅	Item name
cacheRequest	`{ ifNoneMatch?: string; ifModifiedSince?: string; cacheControl?: object }`	optional	Cache validation parameters
locale	`string`	optional	Resolved response locale. Folded into the ETag so a language switch never returns a stale-locale 304 — metadata is translated after the cache validator check (issue #1319).

GetMetaItemCachedResponse

Properties

Property	Type	Required	Description
data	`any`	optional	Metadata payload (omitted for 304 Not Modified)
etag	`{ value: string; weak: boolean }`	optional	ETag for this resource version
lastModified	`string`	optional	Last modification timestamp
cacheControl	`{ directives: Enum<'public' \| 'private' \| 'no-cache' \| 'no-store' \| 'must-revalidate' \| 'max-age'>[]; maxAge?: number; staleWhileRevalidate?: number; staleIfError?: number }`	optional	Cache control directives
notModified	`boolean`	✅	True if resource has not been modified (304 response)
version	`string`	optional	Metadata version identifier

GetMetaItemRequest

Properties

Property	Type	Required	Description
type	`string`	✅	Metadata type name
name	`string`	✅	Item name (snake_case identifier)
packageId	`string`	optional	Optional package ID to filter items by

GetMetaItemResponse

Properties

Property	Type	Required	Description
type	`string`	✅	Metadata type name
name	`string`	✅	Item name
item	`any`	✅	Metadata item definition

GetMetaItemsRequest

Properties

Property	Type	Required	Description
type	`string`	✅	Metadata type name (e.g., "object", "plugin")
packageId	`string`	optional	Optional package ID to filter items by

GetMetaItemsResponse

Properties

Property	Type	Required	Description
type	`string`	✅	Metadata type name
items	`any[]`	✅	Array of metadata items

GetMetaTypesRequest

Properties

Property	Type	Required	Description

GetMetaTypesResponse

Properties

Property	Type	Required	Description
types	`string[]`	✅	Available metadata type names (e.g., "object", "plugin", "view")
entries	`{ type: string; label: string; description?: string; filePatterns: string[]; … }[]`	optional	Enriched per-type registry entries (Phase 3a)

GetNotificationPreferencesRequest

Properties

Property	Type	Required	Description

GetNotificationPreferencesResponse

Properties

Property	Type	Required	Description
preferences	`{ email: boolean; push: boolean; inApp: boolean; digest: Enum<'none' \| 'daily' \| 'weekly'>; … }`	✅	Current notification preferences

GetObjectPermissionsRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name to get permissions for

GetObjectPermissionsResponse

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
permissions	`{ allowCreate: boolean; allowRead: boolean; allowEdit: boolean; allowDelete: boolean; … }`	✅	Object-level permissions
fieldPermissions	`Record<string, { readable: boolean; editable: boolean }>`	optional	Field-level permissions keyed by field name

GetPresenceRequest

Properties

Property	Type	Required	Description
channel	`string`	✅	Channel to get presence for

GetPresenceResponse

Properties

Property	Type	Required	Description
channel	`string`	✅	Channel name
members	`{ userId: string; status: Enum<'online' \| 'away' \| 'busy' \| 'offline'>; lastSeen: string; metadata?: Record<string, any> }[]`	✅	Active members and their presence state

GetTranslationsRequest

Properties

Property	Type	Required	Description
locale	`string`	✅	BCP-47 locale code
namespace	`string`	optional	Translation namespace (e.g., objects, apps, messages)
keys	`string[]`	optional	Specific translation keys to fetch

GetTranslationsResponse

Properties

Property	Type	Required	Description
locale	`string`	✅	Locale code
translations	`{ objects?: Record<string, { label: string; pluralLabel?: string; description?: string; fields?: Record<string, { label?: string; help?: string; placeholder?: string; options?: Record<string, string> }>; … }>; apps?: Record<string, { label: string; description?: string; navigation?: Record<string, { label: string }> }>; messages?: Record<string, string>; validationMessages?: Record<string, string>; … }`	✅	Translation data

GetUiViewRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name (snake_case)
type	`Enum<'list' \| 'form'>`	✅	View type

GetUiViewResponse

Properties

Property	Type	Required	Description
list	`{ name?: string; label?: string; type?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record<string, any> }; … }`	optional
form	`{ type?: Enum<'simple' \| 'tabbed' \| 'wizard' \| 'split' \| 'drawer' \| 'modal'>; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }`	optional
listViews	`Record<string, { name?: string; label?: string; type?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record<string, any> }; … }>`	optional	Additional named list views (views mode — dropdown userFilters allowed, no tabs; ADR-0047)
formViews	`Record<string, { type?: Enum<'simple' \| 'tabbed' \| 'wizard' \| 'split' \| 'drawer' \| 'modal'>; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }>`	optional	Additional named form views
protection	`{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }`	optional	Package author protection block — lock policy for this view.
_lock	`Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>`	optional	Item-level lock — controls overlay & delete (ADR-0010).
_lockReason	`string`	optional	Human-readable reason shown when a write is refused by _lock.
_lockSource	`Enum<'artifact' \| 'package' \| 'env-forced'>`	optional	Layer that set _lock (artifact \| package \| env-forced).
_provenance	`Enum<'package' \| 'org' \| 'env-forced'>`	optional	Origin of the item (package \| org \| env-forced).
_packageId	`string`	optional	Owning package machine id.
_packageVersion	`string`	optional	Owning package version.
_lockDocsUrl	`string`	optional	Optional documentation link surfaced next to _lockReason.

GetViewRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name (snake_case)
viewId	`string`	✅	View identifier

GetViewResponse

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
view	{ list?: object; form?: object; listViews?: Record<string, { name?: string; label?: string; type?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record<string, any> }; … }>; formViews?: Record<string, { type?: Enum<'simple' \| 'tabbed' \| 'wizard' \| 'split' \| 'drawer' \| 'modal'>; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }>; … }	✅	View definition

GetWorkflowConfigRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name to get workflow config for

GetWorkflowConfigResponse

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
workflows	`{ id: string; description?: string; contextSchema?: Record<string, any>; initial: string; … }[]`	✅	Active state-machine workflows for this object

GetWorkflowStateRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
recordId	`string`	✅	Record ID to get workflow state for

GetWorkflowStateResponse

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
recordId	`string`	✅	Record ID
state	`{ currentState: string; availableTransitions: { name: string; targetState: string; label?: string; requiresApproval: boolean }[]; history?: { fromState: string; toState: string; action: string; userId: string; … }[] }`	✅	Current workflow state and available transitions

HttpFindQueryParams

Properties

Property	Type	Required	Description
filter	`string`	optional	JSON-encoded filter expression (canonical, singular).
filters	`string`	optional	JSON-encoded filter expression (deprecated plural alias).
select	`string`	optional	Comma-separated list of fields to retrieve.
sort	`string`	optional	Sort expression (e.g. "name asc,created_at desc" or "-created_at").
orderBy	`string`	optional	Alias for sort (OData compatibility).
top	`number`	optional	Max records to return (limit).
skip	`number`	optional	Records to skip (offset).
expand	`string`	optional	Comma-separated list of lookup/master_detail field names to expand. Resolved to populate array and passed to the engine for batch $in expansion.
search	`string`	optional	Full-text search query.
distinct	`boolean`	optional	SELECT DISTINCT flag.
count	`boolean`	optional	Include total count in response.

ListNotificationsRequest

Properties

Property	Type	Required	Description
read	`boolean`	optional	Filter by read status
type	`string`	optional	Filter by notification type
limit	`number`	✅	Maximum number of notifications to return
cursor	`string`	optional	Pagination cursor

ListNotificationsResponse

Properties

Property	Type	Required	Description
notifications	`{ id: string; type: string; title: string; body: string; … }[]`	✅	List of notifications
unreadCount	`number`	✅	Total number of unread notifications
cursor	`string`	optional	Next page cursor

ListViewsRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name (snake_case)
type	`Enum<'list' \| 'form'>`	optional	Filter by view type

ListViewsResponse

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
views	{ list?: object; form?: object; listViews?: Record<string, { name?: string; label?: string; type?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record<string, any> }; … }>; formViews?: Record<string, { type?: Enum<'simple' \| 'tabbed' \| 'wizard' \| 'split' \| 'drawer' \| 'modal'>; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }>; … }[]	✅	Array of view definitions

MarkAllNotificationsReadRequest

Properties

Property	Type	Required	Description

MarkAllNotificationsReadResponse

Properties

Property	Type	Required	Description
success	`boolean`	✅	Whether the operation succeeded
readCount	`number`	✅	Number of notifications marked as read

MarkNotificationsReadRequest

Properties

Property	Type	Required	Description
ids	`string[]`	✅	Notification IDs to mark as read

MarkNotificationsReadResponse

Properties

Property	Type	Required	Description
success	`boolean`	✅	Whether the operation succeeded
readCount	`number`	✅	Number of notifications marked as read

NotificationPreferences

Properties

Property	Type	Required	Description
email	`boolean`	✅	Receive email notifications
push	`boolean`	✅	Receive push notifications
inApp	`boolean`	✅	Receive in-app notifications
digest	`Enum<'none' \| 'daily' \| 'weekly'>`	✅	Email digest frequency
channels	`Record<string, { enabled: boolean; email?: boolean; push?: boolean }>`	optional	Per-channel notification preferences

RealtimeConnectRequest

Properties

Property	Type	Required	Description
transport	`Enum<'websocket' \| 'sse' \| 'polling'>`	optional	Preferred transport protocol
channels	`string[]`	optional	Channels to subscribe to on connect
token	`string`	optional	Authentication token

RealtimeConnectResponse

Properties

Property	Type	Required	Description
connectionId	`string`	✅	Unique connection identifier
transport	`Enum<'websocket' \| 'sse' \| 'polling'>`	✅	Negotiated transport protocol
url	`string`	optional	WebSocket/SSE endpoint URL

RealtimeDisconnectRequest

Properties

Property	Type	Required	Description
connectionId	`string`	optional	Connection ID to disconnect

RealtimeDisconnectResponse

Properties

Property	Type	Required	Description
success	`boolean`	✅	Whether disconnection succeeded

RealtimeSubscribeRequest

Properties

Property	Type	Required	Description
channel	`string`	✅	Channel name to subscribe to
events	`string[]`	optional	Specific event types to listen for
filter	`Record<string, any>`	optional	Event filter criteria

RealtimeSubscribeResponse

Properties

Property	Type	Required	Description
subscriptionId	`string`	✅	Unique subscription identifier
channel	`string`	✅	Subscribed channel name

RealtimeUnsubscribeRequest

Properties

Property	Type	Required	Description
subscriptionId	`string`	✅	Subscription ID to cancel

RealtimeUnsubscribeResponse

Properties

Property	Type	Required	Description
success	`boolean`	✅	Whether unsubscription succeeded

RegisterDeviceRequest

Properties

Property	Type	Required	Description
token	`string`	✅	Device push notification token
platform	`Enum<'ios' \| 'android' \| 'web'>`	✅	Device platform
deviceId	`string`	optional	Unique device identifier
name	`string`	optional	Device friendly name

RegisterDeviceResponse

Properties

Property	Type	Required	Description
deviceId	`string`	✅	Registered device ID
success	`boolean`	✅	Whether registration succeeded

SaveMetaItemRequest

Properties

Property	Type	Required	Description
type	`string`	✅	Metadata type name
name	`string`	✅	Item name
item	`any`	✅	Metadata item definition

SaveMetaItemResponse

Properties

Property	Type	Required	Description
success	`boolean`	✅
message	`string`	optional

SetPresenceRequest

Properties

Property	Type	Required	Description
channel	`string`	✅	Channel to set presence in
state	`{ userId: string; status: Enum<'online' \| 'away' \| 'busy' \| 'offline'>; lastSeen: string; metadata?: Record<string, any> }`	✅	Presence state to set

SetPresenceResponse

Properties

Property	Type	Required	Description
success	`boolean`	✅	Whether presence was set

UnregisterDeviceRequest

Properties

Property	Type	Required	Description
deviceId	`string`	✅	Device ID to unregister

UnregisterDeviceResponse

Properties

Property	Type	Required	Description
success	`boolean`	✅	Whether unregistration succeeded

UpdateDataRequest

Properties

Property	Type	Required	Description
object	`string`	✅	The object name.
id	`string`	✅	The ID of the record to update.
data	`Record<string, any>`	✅	The fields to update (partial update).
expectedVersion	`string`	optional	Optimistic concurrency token (typically the `updated_at` value the client read). When provided, the server compares it against the current record version and returns 409 CONCURRENT_UPDATE if they differ. Optional — omit to skip the check.

UpdateDataResponse

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
id	`string`	✅	Updated record ID
record	`Record<string, any>`	✅	Updated record
droppedFields	`{ object: string; fields: string[]; reason: Enum<'readonly' \| 'readonly_when'> }[]`	optional	Write-observability (#3407/#3431): caller-supplied fields the engine LEGALLY stripped from the write before persisting — static `readonly` (#2948) or a TRUE `readonlyWhen` predicate (#3042). Present ONLY when ≥1 field was dropped; the update still succeeded without them (status/success semantics unchanged — stripping is legitimate, not an error). REST additionally surfaces this as the `X-ObjectStack-Dropped-Fields` response header. Optional — omit-when-empty keeps the shape backward-compatible for existing clients that only read `record`.

UpdateManyDataRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
records	`{ id: string; data: Record<string, any> }[]`	✅	Array of updates
options	`{ atomic: boolean; returnRecords: boolean; continueOnError: boolean; validateOnly: boolean }`	optional	Update options

UpdateManyDataResponse

Properties

Property	Type	Required	Description
success	`boolean`	✅	Operation success status
error	`{ code: string; message: string; category?: string; details?: any; … }`	optional	Error details if success is false
meta	`{ timestamp: string; duration?: number; requestId?: string; traceId?: string }`	optional	Response metadata
operation	`Enum<'create' \| 'update' \| 'upsert' \| 'delete'>`	optional	Operation type that was performed
total	`number`	✅	Total number of records in the batch
succeeded	`number`	✅	Number of records that succeeded
failed	`number`	✅	Number of records that failed
results	`{ id?: string; success: boolean; errors?: { code: string; message: string; category?: string; details?: any; … }[]; data?: Record<string, any>; … }[]`	✅	Detailed results for each record

UpdateNotificationPreferencesRequest

Properties

Property	Type	Required	Description
preferences	`{ email?: boolean; push?: boolean; inApp?: boolean; digest?: Enum<'none' \| 'daily' \| 'weekly'>; … }`	✅	Preferences to update

UpdateNotificationPreferencesResponse

Properties

Property	Type	Required	Description
preferences	`{ email: boolean; push: boolean; inApp: boolean; digest: Enum<'none' \| 'daily' \| 'weekly'>; … }`	✅	Updated notification preferences

UpdateViewRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name (snake_case)
viewId	`string`	✅	View identifier
data	{ list?: object; form?: object; listViews?: Record<string, { name?: string; label?: string; type?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record<string, any> }; … }>; formViews?: Record<string, { type?: Enum<'simple' \| 'tabbed' \| 'wizard' \| 'split' \| 'drawer' \| 'modal'>; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }>; … }	✅	Partial view data to update

UpdateViewResponse

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
viewId	`string`	✅	Updated view identifier
view	{ list?: object; form?: object; listViews?: Record<string, { name?: string; label?: string; type?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record<string, any> }; … }>; formViews?: Record<string, { type?: Enum<'simple' \| 'tabbed' \| 'wizard' \| 'split' \| 'drawer' \| 'modal'>; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }>; … }	✅	Updated view definition

WorkflowState

Properties

Property	Type	Required	Description
currentState	`string`	✅	Current workflow state name
availableTransitions	`{ name: string; targetState: string; label?: string; requiresApproval: boolean }[]`	✅	Available transitions from current state
history	`{ fromState: string; toState: string; action: string; userId: string; … }[]`	optional	State transition history

WorkflowTransitionRequest

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
recordId	`string`	✅	Record ID
transition	`string`	✅	Transition name to execute
comment	`string`	optional	Optional comment for the transition
data	`Record<string, any>`	optional	Additional data for the transition

WorkflowTransitionResponse

Properties

Property	Type	Required	Description
object	`string`	✅	Object name
recordId	`string`	✅	Record ID
success	`boolean`	✅	Whether the transition succeeded
state	`{ currentState: string; availableTransitions: { name: string; targetState: string; label?: string; requiresApproval: boolean }[]; history?: { fromState: string; toState: string; action: string; userId: string; … }[] }`	✅	New workflow state after transition

Uh oh!

FilesExpand file tree

protocol.mdx

Latest commit

History

protocol.mdx

File metadata and controls

TypeScript Usage

AiInsightsRequest

Properties

AiInsightsResponse

Properties

AiNlqRequest

Properties

AiNlqResponse

Properties

AiSuggestRequest

Properties

AiSuggestResponse

Properties

AutomationActionsResponse

Properties

AutomationTriggerRequest

Properties

AutomationTriggerResponse

Properties

BatchDataRequest

Properties

BatchDataResponse

Properties

CheckPermissionRequest

Properties

CheckPermissionResponse

Properties

CreateDataRequest

Properties

CreateDataResponse

Properties

CreateManyDataRequest

Properties

CreateManyDataResponse

Properties

CreateViewRequest

Properties

CreateViewResponse

Properties

DeleteDataRequest

Properties

DeleteDataResponse

Properties

DeleteManyDataRequest

Properties

DeleteManyDataResponse

Properties

DeleteMetaItemRequest

Properties

DeleteMetaItemResponse

Properties

DeleteViewRequest

Properties

DeleteViewResponse

Properties

FindDataRequest

Properties

FindDataResponse

Properties

GetDataRequest

Properties

GetDataResponse

Properties

GetDiscoveryRequest

Properties

GetDiscoveryResponse

Properties

GetEffectivePermissionsRequest

Properties

GetEffectivePermissionsResponse

Properties

GetFieldLabelsRequest

Properties