API Surface

Overview

Stratum exposes a REST API for programmatic access to upload, analytics, and SQL query capabilities. The OpenAPI reference is at API Reference.

Authentication model

All authenticated API routes use:

Authorization: Bearer <token>

There are two practical token sources today:

• interactive user sessions
• service-account API keys created in the product UI

Service-account keys are still enforced as bearer-authenticated calls. The key determines what kind of token can be issued and what routes it can access.

Available endpoints

• Upload — ingest STDF files
• Ingest jobs — track file processing status
• Lots — list and query uploaded lots
• Analytics — wafer maps, test results, CPK, bin summaries, and pinned agent evaluation
• SQL — run queries against your data

API key scopes

Service accounts use scoped keys:

Scope	Access
ingest	Upload files, read job status
read	Public lot, ingest-status, read-only analytics, schema, and SQL-example routes
full	Public reads plus upload, upload inspection, and SQL execution

Typical permission patterns:

Task	Scope needed
Upload STDF	ingest or full
Check job status	ingest, read, or full
Query analytics	read or full
Evaluate a selection and proposed limits	read or full
Run SQL	full

Response contract today

Successful responses are JSON.

For alpha, many non-2xx responses still return plain-text bodies instead of structured JSON envelopes. That is current product reality, not a missing feature in the docs.

Plan around:

• 401, 403, 404, 409, and many 400 errors returning plain text
• 429 rate-limit responses returning plain text plus rate-limit headers

Analytics endpoints

Read-only query surfaces for lot data:

• wafers and die maps
• test results
• CPK summaries
• bin definitions
• lot metadata
• reproducible selection predicates and exact proposed-limit evaluation

POST /api/analytics/evaluate is the read-only automation counterpart to interactive brushing and what-if limits. It accepts stable predicates rather than browser pixels or a serialized selection mask, pins the request to an exact snapshot, and returns aggregate impact without changing saved work or production limits. See Agent Analysis API.

UI endpoints that edit scenarios or saved analyses remain internal to the product.

Snapshots and analytics semantics

Most analytics routes accept snapshot_job_id.

Use it when you need a frozen analytical view instead of the lot’s current active ingest. This is the main reproducibility mechanism for external integrations.

Capability semantics today:

• stacked lot Cp/Cpk use within-wafer sigma when available
• stacked lot Pp/Ppk use overall lot sigma
• single-wafer views often make capability and performance match because there is no subgroup drift left
• eligible CPK rows include normal_tail, which compares the canonical observed fail rate with the rate predicted from the row’s mean, overall sigma, and active one- or two-sided limits under a normal reference model

normal_tail is distribution-shape evidence, not a disposition result. It is null for estimated counts, fewer than 30 canonical measurements, missing or invalid limits, and non-positive population sigma. The expected lower, upper, and total rates, expected count, observed rate, signed ppm difference, and a bounded observed-to-expected ratio all use the same snapshot, retest, site, return-index, override, and what-if semantics as their parent CPK row. For an eligible row, the observed failure count is the number of canonical measurements outside the active limits, not an unrelated tester or part-level verdict. Rows without active limits do not receive a normal-tail reference. In the Analyze table, Near model means the signed difference is within the larger of 50 ppm or three binomial standard errors under the fitted normal reference. This category is a display aid; the API returns the underlying values rather than asserting that the data is normally distributed.

If you are validating capability numbers against JMP or another external tool, prefer Exact raw in Analysis Defaults instead of summary-backed Auto.

SQL access

The SQL editor is backed by API endpoints for:

• schema discovery
• query execution
• result pagination

Analysis context (selected lot, die subset, scenario limits) carries into SQL automatically.

Current SQL execution guardrails:

• exactly one SELECT or EXPLAIN statement per request
• read-only validation; mutating statements are rejected
• filesystem, network, and export helpers are blocked
• 30s timeout
• hard cap of 100,000 rows per request
• default page size of 1,000 rows when limit is omitted

API keys

Keys are created and revoked through the authenticated product UI. The UI uses admin API routes, but service-account keys cannot list, create, or revoke API keys themselves.

Versioning expectations

The published OpenAPI is still an alpha contract.

That means:

• the surface is good enough for pilots and lightweight internal integrations
• snapshot-aware analytics and ingest routes are intentional and should remain
• route names, loose metadata payloads, and some error formats are still subject to cleanup before a broader long-term compatibility promise

Current limits

• No public SDK yet
• Saved-work collaboration and admin routes are still UI-only
• Agent evaluation cannot save an analysis, approve a proposal, or apply limits
• Upload-size limits are deployment-defined today and are not yet a stable API contract
• Best suited for data ingestion, analytics reads, and lightweight internal integrations

Rate limiting

Current route buckets are enforced server-side and surfaced through x-ratelimit-* headers:

• analytics GET routes: 60/min
• SQL query execution: 30/min
• upload and upload inspect: 10/min

These limits are part of the current alpha deployment posture and may change before a broader public API commitment.