Observability — APIs

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

AlertRuleService

REST (public endpoints need a scope; every call carries trusted tenant and project scope)

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/factory/alerts	ListAlerts	factory.operations.read	read	natural	GW-03	Alert instances by state and severity with sources and notifications.
POST	/factory/alerts/{alertId}/acknowledge	AcknowledgeAlert	factory.operations.operate	shared-write	natural	GW-03	Acknowledge an alert (Operator).
POST	/factory/alerts/{alertId}/resolve	ResolveAlert	factory.operations.operate	shared-write	natural	GW-03	Resolve manually with a reason.
GET	/factory/alert-rules	ListAlertRules	factory.operations.read	read	natural	GW-03	Rules in scope.
PUT	/factory/alert-rules/{name}	SetAlertRule	factory.operations.admin	shared-write	natural	GW-03	Create or change a tenant rule with routes through connectors.

DashboardService

REST (public endpoints need a scope; every call carries trusted tenant and project scope)

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/factory/operations/runs	ListRunProjections	factory.runs.read	read	natural	GW-03	Runs in scope with state, counts, cost by status and waits; the Studio run list.
GET	/factory/operations/runs/{runId}	GetRunTimeline	factory.runs.read	read	natural	GW-03	The §51 trace tree as a timeline: steps, attempts, model and tool receipts, context snapshots, approvals, decisions, usage.
GET	/factory/operations/overview	GetOverview	factory.operations.read	read	natural	GW-03	Tenant and project overview metrics per window.
GET	/factory/operations/overview/{kind}/{subjectId}	GetSubjectOverview	factory.operations.read	read	natural	GW-03	Agent performance, tool reliability or model usage for one subject.
POST	/factory/operations/runs/{runId}/rebuild	RebuildRunProjection	factory.operations.admin	shared-write	natural	GW-03	Rebuild one run's projection from Run Control's journal and the producers' events (Operator).

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Operations	Subscribe	server	internal	read	Stream projection updates for runs in scope to the Studio BFF.

FeedbackService

REST (public endpoints need a scope; every call carries trusted tenant and project scope)

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
POST	/factory/feedback	RecordFeedback	factory.feedback.write	shared-write	key-header	GW-03	Record feedback on a run, attempt, artifact, memory or evaluation.
GET	/factory/feedback	ListFeedback	factory.feedback.read	read	natural	GW-03	Feedback by subject and kind.
GET	/factory/evaluation/datasets	ListDatasets	factory.evaluation.read	read	natural	GW-03	Datasets with versions, task counts and classification.
POST	/factory/evaluation/datasets/{datasetId}/snapshot	SnapshotDataset	factory.evaluation.run	shared-write	key-header	GW-03	Publish a new immutable version of a dataset.
GET	/factory/learning/proposals	ListLearningProposals	factory.evaluation.read	read	natural	GW-03	Proposals by state, kind and target with evidence and expected effect.
POST	/factory/learning/proposals/{proposalId}/decide	DecideLearningProposal	factory.assets.write	shared-write	natural	GW-03	Accept (opens a Draft release in BC-04) or reject with a reason (Asset maintainer).

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Learning	GetDatasetSnapshot	none	internal	read	Resolve a dataset version to its snapshot artifact for a suite.

ObservabilityHost

REST (public endpoints need a scope; every call carries trusted tenant and project scope)

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/observability/health	ObservabilityHealth	factory.health.read	read	natural	GW-01	Liveness, readiness and dependency health (projection store, OpenTelemetry backends, model gateway for evaluation, inbox lag).
GET	/observability/meta/backends	ObservabilityBackends	factory.meta.read	read	natural	GW-03	Configured OpenTelemetry backends (traces, metrics, logs) and the GenAI semantic-convention version in use.

QualityScoreService

REST (public endpoints need a scope; every call carries trusted tenant and project scope)

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/factory/evaluation/suites	ListEvaluationSuites	factory.evaluation.read	read	natural	GW-03	Active suites per target with thresholds, datasets and baseline rules.
POST	/factory/evaluation/runs	StartEvaluation	factory.evaluation.run	sandbox	key-header	GW-03	Evaluate a target release (and baseline) with a suite; runs as sandbox-class Factory runs under the evaluation project.
GET	/factory/evaluation/runs/{evaluationId}	GetEvaluation	factory.evaluation.read	read	natural	GW-03	State, per-metric results for target and baseline, verdict, cost, duration, evidence reference.
POST	/factory/evaluation/runs/{evaluationId}/waive	WaiveEvaluation	factory.evaluation.waive	publication	natural	GW-03	Record a waiver (approval-gated, class publication) with a reason; the verdict becomes Waived and evidence says so.
GET	/factory/asset-releases/{releaseId}/evaluations	ListReleaseEvaluations	factory.evaluation.read	read	natural	GW-03	Evaluations of a release with verdicts (the evidence Asset Publication reads).

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Evaluation	GetVerdict	none	internal	read	The latest verdict and evidence reference for a release and suite; used by Asset Publication at the Published gate (ADR-0021).
Evaluation	RunSuite	none	internal	sandbox	Start an evaluation (publication, model deployments, regression).

SloService

REST (public endpoints need a scope; every call carries trusted tenant and project scope)

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/factory/slos	ListSlos	factory.operations.read	read	natural	GW-03	Objectives in scope with current state, value and error budget.
PUT	/factory/slos/{subjectKind}/{subjectId}/{kind}	SetSlo	factory.operations.admin	shared-write	natural	GW-03	Define or tighten an objective for a subject (tenant objectives stricter than platform only).
GET	/factory/health/services	ListServiceHealth	factory.operations.read	read	natural	GW-03	Health rollup of every host with dependency states (Studio status page).