Control Plane — 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.

AgentCardService

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/agent-cards	ListAgentCards	factory.agents.discover	read	natural	GW-01	Discover cards visible to the caller (tenant, partner or public).
GET	/factory/agent-cards/{agentId}	GetAgentCard	factory.agents.discover	read	natural	GW-01	The A2A agent card of an agent's current Published release.
POST	/factory/agent-cards/{agentId}/tasks	SubmitA2ATask	factory.agents.invoke	shared-write	key-header	GW-01	Inbound A2A task; mapped onto a run submission with the caller's workload identity and delegated scope.
GET	/factory/agent-cards/{agentId}/tasks/{taskId}	GetA2ATask	factory.agents.invoke	read	natural	GW-01	Task state projected from the run (submitted, working, input-required, completed, failed, cancelled).

AgentRegistryService

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/asset-releases/validate	ValidateRelease	factory.assets.write	sandbox	natural	GW-03	Resolve the closure of a candidate from Git and report missing, unreviewed or incompatible dependencies without publishing.
POST	/factory/asset-releases	SubmitRelease	factory.assets.write	publication	key-header	GW-03	Create an InReview release candidate from a source commit; triggers evaluation.
POST	/factory/asset-releases/{releaseId}/publish	PublishRelease	factory.assets.publish	publication	natural	GW-03	Move an InReview candidate to Published after gates and approval (approval-gated action).
POST	/factory/asset-releases/{releaseId}/deprecate	DeprecateRelease	factory.assets.publish	publication	natural	GW-03	Deprecate a Published release with an in-flight policy.
GET	/factory/asset-releases/{releaseId}	GetRelease	factory.assets.read	read	natural	GW-03	Manifest, closure, evidence and aliases.
GET	/factory/asset-releases	ListReleases	factory.assets.read	read	natural	GW-03	Releases filtered by kind, asset, state.
PUT	/factory/assets/{assetKind}/{assetId}/aliases/{name}	MoveAlias	factory.assets.publish	publication	natural	GW-03	Point an alias at a Published release; accepted runs are unaffected.

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
AssetPublication	ResolveRelease	none	internal	read	Resolve an alias or release id to an immutable release with its closure; used by Run Control at submission.
AssetPublication	LoadRelease	server	internal	read	Stream the manifest and closure content references for release loading in the runtime (BC-06).

ControlPlaneApi

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/health	Health	factory.health.read	read	natural	GW-01	Liveness, readiness and dependency health of the host and its modules (HealthChecks aggregator feed).
GET	/factory/meta/modules	ListModules	factory.meta.read	read	natural	GW-03	Modules loaded in this host with their versions and schema ownership; used by the Studio about page and operators.

CostUsageService

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/projects/{projectId}/usage	GetProjectUsage	factory.usage.read	read	natural	GW-03	Usage by meter and status (estimated, reserved, observed, reconciled, uncertain) for a period.
GET	/factory/runs/{runId}/usage	GetRunUsage	factory.usage.read	read	natural	GW-03	Usage records and the reservation of one run.
PUT	/factory/projects/{projectId}/budget	SetProjectBudget	factory.usage.admin	shared-write	natural	GW-03	Set the project budget and a threshold not above the platform's.

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Usage	Reserve	none	internal	spend	Reserve an estimated amount for a run; returns Reserved, Denied or approval-required.
Usage	RecordUsage	none	internal	shared-write	Record metered usage from a model or tool receipt (idempotent on receipt id).

EnvironmentService

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/projects/{projectId}/environments	CreateEnvironment	factory.projects.admin	shared-write	key-header	GW-03	Create an environment with a policy class.
GET	/factory/projects/{projectId}/environments	ListEnvironments	factory.projects.read	read	natural	GW-03	Environments of a project with state and class.
POST	/factory/environments/{environmentId}/freeze	FreezeEnvironment	factory.projects.admin	production	natural	GW-03	Block writes and production actions (incident or change freeze).
POST	/factory/environments/{environmentId}/unfreeze	UnfreezeEnvironment	factory.projects.admin	production	natural	GW-03	Lift a freeze.

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Environments	GetPolicyClass	none	internal	read	Return the environment class and state for policy evaluation of a tool call.

FactoryCommercialService

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/subscription	GetSubscription	factory.commercial.read	read	natural	GW-03	The tenant's subscription, edition, seats and current period.
PUT	/factory/subscription	ChangeSubscription	factory.commercial.admin	spend	key-header	GW-03	Change edition or seats (Platform admin of the tenant); takes effect at the next period unless upgraded.
GET	/factory/invoices	ListInvoices	factory.commercial.read	read	natural	GW-03	Invoices with usage snapshots.

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Commercial	GetEntitlements	none	internal	read	Edition entitlements and quotas for BC-33 checks.

ProjectService

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/projects	CreateProject	factory.projects.write	shared-write	key-header	GW-03	Create a project in the caller's tenant; the caller becomes Workspace admin.
GET	/factory/projects	ListProjects	factory.projects.read	read	natural	GW-03	Projects the caller is a member of.
GET	/factory/projects/{projectId}	GetProject	factory.projects.read	read	natural	GW-03	Project with memberships, delegations, source scope and environments.
PUT	/factory/projects/{projectId}/members/{subjectId}	SetMembership	factory.projects.admin	shared-write	natural	GW-03	Grant or change a project role (Workspace admin).
POST	/factory/projects/{projectId}/delegations	Delegate	factory.projects.delegate	shared-write	key-header	GW-03	Delegate the same or a lesser role for a bounded period with a reason (D18).
DELETE	/factory/projects/{projectId}/delegations/{delegationId}	RevokeDelegation	factory.projects.delegate	shared-write	natural	GW-03	Revoke a delegation immediately.
PUT	/factory/projects/{projectId}/source-scope	SetSourceScope	factory.projects.admin	shared-write	natural	GW-03	Replace the repositories, document collections and tools a run may touch.
POST	/factory/projects/{projectId}/close	CloseProject	factory.projects.admin	production	natural	GW-03	Start off-boarding (cancel runs, revoke delegations, export or delete per tenant policy).

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Projects	ResolveScope	none	internal	read	Resolve a subject's roles, source scope and policy override for a project; used by every module at request time.

RunControlService

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/runs	SubmitRun	factory.runs.write	shared-write	key-header	GW-03	Accept a run; 202 with the run location; idempotent on Idempotency-Key.
GET	/factory/runs/{runId}	GetRun	factory.runs.read	read	natural	GW-03	Run with steps, attempts, current lease and pending approvals.
GET	/factory/runs	ListRuns	factory.runs.read	read	natural	GW-03	Runs in the trusted scope with state and freshness; paged.
POST	/factory/runs/{runId}/cancel	CancelRun	factory.runs.write	shared-write	natural	GW-03	Record cancellation intent and request interruption; the resulting state is observed, not assumed.
POST	/factory/approvals/{approvalId}/decision	DecideApproval	factory.approvals.decide	shared-write	natural	GW-03	Approve, reject or request changes on the exact proposal version; requires the request version (optimistic concurrency).
GET	/factory/approvals	ListApprovals	factory.approvals.read	read	natural	GW-03	Pending and decided approval requests visible to the caller's roles.

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
RunControl	AcquireLease	none	internal	shared-write	Runtime worker acquires or renews the lease of an attempt; returns the fencing token.
RunControl	ReportAttemptOutcome	none	internal	shared-write	Lease holder reports the single outcome of an attempt with its receipt hash.
RunControl	RequestApproval	none	internal	shared-write	Worker asks for a human decision on an exact proposal before a gated action.
RunControl	WatchRun	server	internal	read	Server stream of run and approval state changes for the BFF and workers.