API Reference

Live reference for the MicroStax REST API — generated directly from the OpenAPI spec. Use it for exact request and response schemas.

---

What This Page Adds

The generated reference above is the schema authority. This page adds the route inventory and transport model so developers and infrastructure teams can see the implemented surface quickly.

Base URL and auth

Base URL

The control plane is usually exposed from your hosted MicroStax API or local development endpoint.

Authentication

Most routes require:

Authorization: Bearer <token>

Some org-scoped clients also send:

X-Organization-ID: <org-id>

Public routes such as health checks, share links, and some portal or webhook endpoints handle auth differently.

Response style

Most JSON APIs use a standard envelope:

{
  "data": {},
  "meta": {
    "requestId": "req_..."
  }
}

Some legacy or infrastructure routes return raw JSON rather than the envelope. Use the generated reference for exact per-route behavior.

Route Inventory

Environment lifecycle

Method	Path	Purpose
POST	/environments	Create an environment from a Blueprint.
GET	/environments	List environments.
GET	/environments/:id	Get one environment.
PATCH	/environments/:id	Update environment settings such as name or auto-shutdown.
DELETE	/environments/:id	Delete an environment.
POST	/environments/:id/stop	Stop an environment.
POST	/environments/:id/resume	Resume a stopped environment.
POST	/environments/:id/retry	Retry provisioning after failure.
GET	/environments/:id/status	Get environment and per-service status.
PATCH	/environments/:id/scale	Scale a service inside an environment.
POST	/environments/validate	Validate a Blueprint.
POST	/environments/import	Import from Compose-like content.
POST	/environments/discover	Discover a Blueprint from a repository URL.

Logs, topology, telemetry, and runtime inspection

Method	Path	Purpose
GET	/environments/:id/logs	Fetch recent environment logs.
GET	/environments/:id/metrics	Environment metrics view.
GET	/environments/:id/deviations	Configuration drift report.
GET	/environments/:id/store-stats	Environment storage stats.
GET	/environments/:id/topology	Service topology graph.
GET	/environments/:id/resolve/:service	Resolve the active provider for a service.
POST	/api/v1/otel/v1/traces	OTEL trace ingest.
GET	/api/v1/telemetry/:envId/recent	Recent telemetry for an environment.
GET	/api/v1/remediation/policies	Current remediation policy surface.

Sharing and public access

Method	Path	Purpose
POST	/environments/:id/share	Generate share metadata and tokenized links.
GET	/share/:token	Public JSON share view with optional PIN query.
GET	/portal/:envId	Public HTML environment portal view.

Baselines, overlays, and shadow environments

Method	Path	Purpose
POST	/baselines	Promote an environment to a baseline.
GET	/baselines	List baselines.
POST	/baselines/:id/overlays	Create an overlay from a baseline.
GET	/baselines/:id/overlays	List overlays for a baseline.
DELETE	/overlays/:id	Delete an overlay.
POST	/baselines/:id/shadows	Create a shadow environment for validation.
GET	/baselines/:id/routing-metrics	Baseline routing metrics.

Data, seeds, snapshots, and replay

Method	Path	Purpose
POST	/environments/:id/seed	Run a one-off seed against an environment.
GET	/environments/snapshots	Global snapshot listing surface.
POST	/environments/:id/snapshots	Create an environment snapshot.
GET	/environments/:id/snapshots	List snapshots for an environment.
POST	/environments/:id/replay	Replay the execution graph, optionally from a snapshot.
POST	/seeds/publish	Publish a seed package.
POST	/seeds/run/:name/:envId	Run a published seed package.
GET	/seeds/search	Search the seed registry.

Diagnostics, remediation, and behavior comparison

Method	Path	Purpose
POST	/environments/:id/diagnose	Run diagnosis for an environment.
POST	/environments/:id/diagnose/apply	Apply a remediation suggestion.
GET	/api/v1/environments/:id/remediation	Inspect remediation options.
POST	/api/v1/environments/:id/apply-remediation/:action	Apply a named remediation action.
POST	/shadow-observe	Record mirrored shadow observations.
GET	/diffs/:id	Retrieve behavioral diffs for an environment.
POST	/api/v1/observations	Ingest structured behavior observations.
GET	/api/v1/observations/:contextId	Fetch observations for one context.
POST	/api/v1/observations/compare/:contextId	Compare observations for a request context.
GET	/api/v1/baselines/:id/diffs	Baseline diff view.
GET	/api/v1/baselines/:id/shadow-accuracy	Shadow accuracy metrics.

Templates, stubs, and registries

Method	Path	Purpose
GET	/templates	List bundled Blueprint templates.
GET	/templates/:id	Fetch one template.
POST	/stubs/generate	Generate service stubs.
GET	/registry/resolve	Resolve registry endpoints for a service/environment pair.
POST	/registry/register	Register a service endpoint in the registry.

Organization, governance, and billing

Method	Path	Purpose
GET	/organization/usage	Current org plan and usage summary.
PATCH	/organization/sso	Update SSO configuration.
GET	/organization/drift-policy	Get drift/governance policy.
PATCH	/organization/drift-policy	Update drift/governance policy.
GET	/organization/compliance-report	Current org compliance report.
POST	/billing/checkout	Start plan checkout.
POST	/billing/simulate-success	Local/dev billing simulation.
POST	/billing/webhook	Billing webhook endpoint.
GET	/billing/usage	Usage and cost records.
GET	/billing/rates	Rate cards.
GET	/admin/metrics/summary	Admin metrics summary.
GET	/admin/metrics/history	Admin metrics history.
GET	/admin/orgs/health	Admin organization health view.
GET	/admin/costs/:orgId	Admin cost report for one org.

Auth, health, federation, and platform infrastructure

Method	Path	Purpose
GET	/auth/sso/discover	Discover SSO availability from email domain.
GET	/auth/sso/login	Begin SSO login redirect flow.
GET	/health	Cluster/API health summary.
GET	/health/live	Liveness.
GET	/health/ready	Readiness.
GET	/health/details	Detailed health view.
GET	/ready	Alternate readiness endpoint.
GET	/metrics	Prometheus metrics.
GET	/status/stats	Status summary endpoint.
POST	/federation/register-provider	Register a federated provider.
GET	/federation/jwks	Local JWKS document.
GET	/federation/providers	List federated providers.
POST	/federation/sync/:id	Trigger federated sync.

Streaming and WebSocket surfaces

Transport	Path	Purpose
WebSocket	/environments/:id/progress	Provisioning progress stream.
WebSocket	CLI log stream transport	The current CLI implementation uses a WebSocket log stream for env logs.

Consumption guidance

• use the generated OpenAPI section above for exact request and response schemas
• expect environment creation and replay to be asynchronous
• poll /environments/:id/status or subscribe to progress events rather than assuming immediate readiness
• use the CLI or MCP server when you want task-oriented behavior instead of direct route orchestration

Recommended entrypoints by use case

Goal	Best surface
low-level integration with exact schemas	REST API
CI/CD orchestration	CLI with --json
agentic automation	MCP server