Model & Compute Platform — 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.

ComputePoolService

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/compute-pools	ListComputePools	factory.compute.read	read	natural	GW-03	Pools with kind, region, boundary, capacity, utilization, queue depth and cached models.
POST	/factory/compute-pools	RegisterComputePool	factory.compute.admin	shared-write	key-header	GW-03	Register a pool (Platform admin; a tenant's Platform admin for hybrid-compute pools).
POST	/factory/compute-pools/{poolId}/drain	DrainComputePool	factory.compute.admin	production	natural	GW-03	Stop new placements and let loaded models finish (production action on serving capacity).
POST	/factory/compute-pools/{poolId}/warm	WarmModel	factory.compute.admin	shared-write	key-header	GW-03	Pre-load a model on a pool before expected demand.
GET	/factory/compute-pools/placements/{placementId}	GetPlacementDecision	factory.compute.read	read	natural	GW-03	Why a pool was chosen or no pool fitted.

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
ComputePools	Place	none	internal	shared-write	Choose a pool for a self-hosted deployment under the request's privacy, region, memory, latency and price constraints; returns the decision id and the endpoint reference.
ComputePools	ReportUtilization	client	internal	shared-write	Pools and their agents report utilization, queue depth and the model cache.

ModelGatewayHost

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

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/model-gateway/health	GatewayHealth	factory.health.read	read	natural	GW-01	Liveness, readiness and per-provider health of this host (adapters, store, policy, usage accounting reachability).
GET	/model-gateway/meta/adapters	GatewayAdapters	factory.meta.read	read	natural	GW-03	Provider adapters loaded in this host with their package versions and supported protocols (OpenAI-compatible, Anthropic-compatible, embeddings, reranking, streaming, structured outputs, tool calls).

ModelRouterService

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/model-profiles	ListModelProfiles	factory.models.read	read	natural	GW-03	Active profiles with capabilities, privacy class, limits and fallback chains.
GET	/factory/model-profiles/{profileId}	GetModelProfile	factory.models.read	read	natural	GW-03	A profile with its allowed deployments and their evidence summary.
GET	/factory/model-deployments	ListModelDeployments	factory.models.admin	read	natural	GW-03	Deployments with provider, region, privacy class, state, health and license metadata (Platform admin and Observer).
POST	/factory/model-deployments	RegisterDeployment	factory.models.admin	shared-write	key-header	GW-03	Register a Candidate deployment (Platform admin); credentials are brokered, never posted.
POST	/factory/model-deployments/{deploymentId}/evaluate	EvaluateDeployment	factory.models.admin	sandbox	key-header	GW-03	Run the capability suite against a deployment (sandbox action; produces evidence through BC-22).
POST	/factory/model-deployments/{deploymentId}/approve	ApproveDeployment	factory.models.admin	publication	natural	GW-03	Move an Evaluated deployment to Approved after license and evidence checks (publication-class action).
POST	/factory/model-profiles/{profileId}/route-plan/preview	PreviewRoutePlan	factory.models.read	read	natural	GW-03	Dry-run the router for a scope and profile: candidates, filters applied, reasons for exclusion.
GET	/factory/runs/{runId}/model-receipts	ListRunReceipts	factory.runs.read	read	natural	GW-03	Invocation receipts of a run (hashes, deployments, usage status, outcome).

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
ModelGateway	ResolveRoutePlan	none	internal	shared-write	Resolve and persist the route plan for a run and profile under the policy revision in force; idempotent per run and profile.
ModelGateway	Invoke	server	internal	spend	Chat completion with tools and structured output through the route plan; streams tokens and ends with the receipt (model-invocation-v1).
ModelGateway	Embed	none	internal	spend	Embeddings through an embedding profile with a receipt.
ModelGateway	Rerank	none	internal	spend	Reranking through a reranker profile with a receipt.