AI and ML
AI adapters and agents, chat sessions, knowledge notes, ML models and their configurations.
75 operations · complete schema 141 KB
magicQuery
Executes a Magic Query string and returns the predefined query's JSON result. On a bad noun or parameter, returns a structured error whose 'extensions' carry 'code', 'actionable_message', and 'suggestions' for self-correction.
getMagicQuerySchema
Returns the input JSON Schema and output introspection for a Magic Query noun, so consumers (especially LLMs) can learn its contract before calling magicQuery.
listMagicQueries
Lists every available Magic Query noun with a short description and its options — the discovery entry point.
getMagicQueryGraphQL
Resolves a Magic Query string to the real GraphQL operation and variables it runs, so consumers can graduate from the façade to raw GraphQL. Does not execute.
listDataChangeEventTopics
List all valid data change event topics, grouped by resource. Requires authentication.
generateDefaultDataQuery
Generate a default GraphQL data query for an event topic. Returns a query string with all scalar fields for the resource, or null if the topic has no matching query. The query uses $id as the variable for the resource ID.
ping
Health check endpoint
getAIAdapter
Fetch an AI adapter by ID. Requires aiadapter:read permission.
listAIAdapters
List AI adapters with pagination and filtering. Requires aiadapter:list permission.
getAIAgent
Fetch an AI agent by ID. Requires aiAgent:read permission.
listAIAgents
List AI agents with pagination. Requires aiAgent:list permission.
getMLModelConfig
Fetch an ML model config by ID. Requires mlmodelconfig:read permission.
listMLModelConfigs
List ML model configs with pagination and filtering. Requires mlmodelconfig:list permission.
exportMLModelConfig
Export an ML model config as JSON or YAML. Requires mlmodelconfig:read permission.
listMLModelConfigVersions
List versions for an ML model config, newest first, with pagination. Requires mlmodelconfig:read permission.
getMLModelConfigVersion
Get a specific ML model config version by ID. Requires mlmodelconfig:read permission.
getChatSession
Fetch a chat session by ID. Requires chatsession:read permission.
listChatSessions
List chat sessions with pagination and filtering. Requires chatsession:list permission.
chatAIAvailability
Report configured adapter eligibility for this tenant. This is not a live provider health check; use testAIAdapter to verify credentials and model access.
iacSchema
The infrastructure-only view of this schema, for declarative tooling. Contains only annotated resources and the types they reach.
iacValidate
Validate an infrastructure artifact. Pure and side-effect free; safe to alias many times in one document.
iacGuides
Every authoring guide, for a tool that syncs them to a folder. Intended for `schema pull` to call once and write to disk, not for an agent to call while authoring — a file can be grepped and re-read in part, where a response arrives whole.
helpChapters
List human-facing manual chapters from the running deployment.
helpChapter
Read a chapter of the current published manual edition.
searchHelp
Search human-facing manuals using shared semantic and text retrieval.
schemaAuthoringCatalog
Compiler-owned vocabulary for the standalone XML JSON Schema dialect, including native form annotations.
compileSchemaXML
Compile standalone XML schema syntax into JSON Schema without persisting it; host restrictions apply when embedded.
renderSchemaXML
Render JSON Schema as native XML without dropping unsupported keywords or changing a saved document.
iacSchemaDocument
Fetch the JSON Schema document a SCHEMA-kind validator references, for declarative tooling.
reportQuery
Execute a MicroSQL reporting query against the analytics schema. Supports SELECT with WHERE, JOIN, ORDER BY, GROUP BY, LIMIT. Tenant isolation is enforced automatically. Covers production (jobs, components, operations, milestones), prepress, scheduling (work_centers, planned_operations, schedule_allocations), sales (estimates, orders, invoices), cost accounting, catalog/inventory (products, substrates, warehouse_stock), logistics (shipments), tasks, time-series (metric_points, progress_points), and people (users, teams). Per-table IAM authorization is enforced — requires :list on each table's resource.
describeQuerySchema
Analyze a MicroSQL query and return the inferred result schema (column names, data types) without executing it. Returns validation errors with typo-correcting suggestions if the query is invalid. Validates only against tables the caller can list.
concept
Fetch a single concept by ID. Requires concept:read permission.
concepts
List the tenant's concepts with pagination. Requires concept:list permission.
knowledgeNote
Fetch a single knowledge note by ID. Requires knowledgeNote:read permission.
knowledgeNotes
List knowledge notes with pagination and filtering. A direct query over the store; for situational relevance use `retrieveKnowledge`. Requires knowledgeNote:list permission.
retrieveKnowledge
The retrieval (RAG) entry point. Given the entities in context (`seeds`) and an optional `query`, returns the most relevant knowledge in two buckets — graph-reached and semantically-supporting — each ranked by a blended relevance score. Requires knowledgeNote:read permission.
upsertAIAdapter
Create or update an AI adapter. Requires aiadapter:write permission.
createAIAdapter
Create a new AI adapter. Requires aiadapter:write permission.
updateAIAdapter
Update an AI adapter. Only provided fields are changed. Requires aiadapter:write permission.
deleteAIAdapter
Delete an AI adapter. Requires aiadapter:delete permission.
testAIAdapter
Verify provider credentials and all effective configured models using provider model endpoints. Does not generate content. Requires aiadapter:read permission.
upsertAIAgent
Create or update an AI agent. Requires aiAgent:write permission.
createAIAgent
Create a new AI agent. Requires aiAgent:write permission.
updateAIAgent
Update an AI agent. Only provided fields are changed. Requires aiAgent:write permission.
deleteAIAgent
Delete an AI agent. Requires aiAgent:delete permission.
upsertMLModelSource
Create or replace ML XML authoring source. Updates require the observed authoring revision and preserve training and publication state.
upsertMLModelConfig
Create or update an ML model config. Requires mlmodelconfig:write permission.
createMLModelConfig
Create a new ML model config. Requires mlmodelconfig:write permission.
updateMLModelConfig
Update an ML model config. Only provided fields are changed. Requires mlmodelconfig:write permission.
deleteMLModelConfig
Delete an ML model config. Requires mlmodelconfig:delete permission.
trainMLModel
Trigger training for an ML model. Requires mlmodelconfig:execute permission.
previewMLModelPipeline
Run the data pipeline over a sample WITHOUT training and return the emitted fields. Requires mlmodelconfig:execute permission.
importMLModelConfig
Import an ML model config from JSON or YAML. Requires mlmodelconfig:write permission.
predictMLModel
Run a prediction using a trained ML model. Requires mlmodelconfig:execute permission.
forecastMLModel
Forecast future values using a trained time-series model. Requires mlmodelconfig:execute permission.
retrainSystemModels
Manually trigger retraining of all system-managed ML models for the current tenant. Requires mlmodelconfig:execute permission.
publishMLModelVersion
Set a version as the published version used for predictions. Requires mlmodelconfig:write permission.
createChatSession
Create a new chat session. Requires chatsession:write permission.
updateChatSession
Update an existing chat session. Requires chatsession:write permission.
deleteChatSession
Delete a chat session. Requires chatsession:delete permission.
sendChatMessage
Send a message to a chat session and receive an AI response. Requires chatsession:write permission.
clearChatMessages
Clear all messages from a chat session. Requires chatsession:write permission.
createConcept
Manually author a concept in the ontology. Requires concept:write permission.
updateConcept
Rename or reclassify an existing concept. Requires concept:write permission.
deleteConcept
Delete a concept. Requires concept:delete permission.
createKnowledgeNote
Contribute a knowledge note about a concept or an entity. Requires knowledgeNote:write permission.
updateKnowledgeNote
Edit a note's body or scope, or supersede it with a replacement. The attachment is immutable. Requires knowledgeNote:write permission.
confirmKnowledgeNote
Endorse a note: increments its confirmation count (raising its retrieval trust weight) and promotes a PENDING note to LIVE. Requires knowledgeNote:write permission.
deleteKnowledgeNote
Delete a note and any graph edges it sourced. Requires knowledgeNote:delete permission.
markKnowledgeNotesContradict
Record that two notes contradict each other; the conflict is surfaced by `retrieveKnowledge` via `KnowledgeHit.contradicts`. Requires knowledgeNote:write permission.
unmarkKnowledgeNotesContradict
Remove a previously recorded contradiction between two notes. Requires knowledgeNote:write permission.
captureKnowledge
Capture a knowledge subgraph — concepts, a note, and instance/semantic edges — in one atomic transaction. The manual, deterministic core of knowledge capture; the Phase-2 LLM path produces this same input. `scope` is caller-controlled. Requires knowledgeNote:write permission.
dataChangeEvents
Subscribe to real-time data change events. Requires read permission on each requested resource.
mlModelTrainingStatus
Stream real-time training status events for an ML model config.
chatMessageStream
Stream AI responses for a chat message in real-time. Emits chunks as they arrive. Requires chatsession:write permission.