Headless by Contract: One API Surface, Four Ways In

The Screen Is Just One Client

Ask an enterprise vendor whether their product "has an API" and the answer is always yes. Ask whether their own UI uses that API and the answer gets quieter. Most enterprise software is built screen-first: the product team ships features against internal endpoints, and sometime later a partial, rate-limited, differently-shaped public API gets bolted on for integrators. Two surfaces, two behaviors, one of them a second-class citizen.

Own360 inverts this. Every one of the 23 OwnApps modules exposes a versioned /api/v1 with a published OpenAPI contract, and everything — the web UI a human clicks, the CLI an engineer scripts, the raw HTTP call a backend service makes, the MCP tool an AI agent invokes — is a client of that same contract. There is no privileged internal path. If the UI can do it, the API can do it, because the UI is doing it through the API.

This sounds like engineering hygiene. It is actually a strategic position. The moment autonomous software becomes a real consumer of your product, the API stops being an integration convenience and becomes the product's primary interface. A vendor whose UI can do things its API cannot has built a product that agents can only partially operate. A vendor whose API is the single surface has built a product where every capability is automatically available to every kind of client — including the kinds that did not exist when the capability shipped.

What the Contract Actually Guarantees

"Contract-first" only means something if the contract carries guarantees stronger than "here are some endpoints." The Own360 headless spec commits every app to a small set of behaviors, and it is the uniformity of those behaviors — not any single one — that makes the whole surface programmable.

Versioned surface, published spec. Every app ships /api/v1 with a published OpenAPI document. The spec is not documentation of the API; it is the source the API is validated against. A client can read the contract and know, mechanically, what the server will accept and return.

Cursor pagination everywhere. Offset pagination breaks under concurrent writes — rows shift, records get skipped or duplicated. Cursor pagination gives every client, human-scripted or agent-driven, a stable way to walk a collection while the system keeps changing underneath it. When a client needs to enumerate ten thousand deals, correctness cannot depend on the database holding still.

Idempotency-Key on every write. Networks fail mid-request. Did the invoice get created before the timeout, or not? Without idempotency, the safe answer is "don't retry," which is no answer at all for autonomous software. With an Idempotency-Key header, a retry with the same key returns the original result instead of creating a duplicate. Retries become boring — which is exactly what you want when the retrying party is an agent running unattended.

RFC 9457 problem details. Errors are structured documents with a type, a title, and machine-readable detail — not HTML error pages or free-text strings. A human can squint at "something went wrong." An agent cannot. Structured failure is what lets a caller distinguish "this deal doesn't exist" from "you lack permission" from "the request body is malformed" and take a different action for each.

entity.changed events on OwnBus. Every state change publishes a signed event to the platform's event spine. Apps publish; they never call each other directly. Any consumer — a workflow, a warehouse sync, another app's automation — reacts to the event stream rather than polling or coupling to another app's internals.

24 CLIs Nobody Hand-Wrote

Here is the test of whether a contract is real: can you generate things from it and trust what comes out?

Own360 generates 24 per-app command-line interfaces directly from the published OpenAPI manifests. owncrm entities lists what the CRM exposes. owncrm deal list --limit 20 walks the deal collection with cursor pagination handled for you. owncrm domain advance_deal invokes a domain action — not a raw table write, but the same business operation the UI button triggers, with the same validations. Authentication is OAuth2 client-credentials, so a CLI session is a first-class identity in the platform, not a borrowed user password.

Nobody sat down to write those CLIs, and that is precisely the point. A hand-written CLI is documentation that compiles: it reflects the API as someone understood it on the day they wrote it, and it decays from that day forward. A generated CLI cannot decay. When the contract changes, the CLI is regenerated; there is no version of events where the tool and the API disagree about what a deal looks like or which parameters advance_deal accepts.

The same manifests feed openapi-to-mcp, which generates Model Context Protocol tool servers for AI clients — the subject of its own essay. One contract, three generated artifact families: CLIs for humans who script, MCP tools for models that act, and the task catalog that makes agent work verifiable.

Why Contract-First Makes Agent Tasks Verifiable

The task catalog deserves its own explanation, because it is where contract-first stops being an engineering preference and becomes an AI safety property.

Own360 ships a verified catalog of 268 single-app tasks and 42 cross-app workflows. "Verified" means each task has been exercised end-to-end against the contract: the inputs it needs, the calls it makes, the events it emits, the state it leaves behind. A quote-to-cash chain runs CRM to ERP to Books with entity ids chained across every hop. A closed deal in CRM triggers an announcement in Chat. A new hire in HRMS produces a Wiki onboarding page and a Tasks checklist.

You can only verify a task like this if every step is a contract operation. If a workflow's third step is "and then the integration clicks through the vendor's UI," verification is theater — the step can silently break with any front-end release, and no schema will tell you. When every step is an OpenAPI operation with typed inputs, typed outputs, structured errors, and an emitted event, verification is mechanical: run the chain, check every response against the schema, confirm the ids connect, confirm the events landed on the bus.

An agent task is verifiable exactly to the degree that every action in it is a contract operation. The contract is not paperwork around the capability — it is what makes the capability checkable.

This is also what makes the catalog composable. The 42 cross-app workflows are not bespoke integrations; they are sequences of the same operations the 268 single-app tasks use, joined by ids and events. New chains are assembled from verified parts, not engineered from scratch.

What Breaks When the API Is an Afterthought

Consider the alternative, because most of the industry lives there. When the API is a retrofit, four predictable failures follow.

Capability gaps. The UI can merge duplicate accounts; the API cannot. The UI can apply a credit note against two invoices; the API exposes only single-invoice application. Every gap is a task an agent cannot perform and a workflow that dead-ends into "a human finishes this in the browser." You discover the gaps one automation project at a time.

Semantic divergence. The UI path validates something the API path does not, or applies a default the API omits. Now the same logical action produces different state depending on the door it came through. Auditors notice this before engineers do.

Unverifiable automation. Without idempotency guarantees and structured errors, every automation carries manual failure analysis inside it. Retry logic becomes guesswork. Teams respond rationally: they automate less, or they automate through screen-scraping and browser robots — the most fragile possible client pretending to be the most privileged one. The integration cost problem is largely this failure compounding across a portfolio.

Tool rot. Any CLI, SDK, or agent tool built against a retrofit API is hand-maintained, which means it lags the API, which means it lies. The worst version of this is an AI agent with a confidently wrong tool definition — it will not error, it will act on stale semantics.

None of these are bugs. They are the structural consequence of treating the API as a feature rather than the product's foundation.

One Surface, Governed Once

There is a final dividend, and it belongs to the control plane. Because every client comes through the same contract, OwnCentral can govern the whole surface in one place: OAuth2 client-credential identities for every non-human caller, RBAC evaluated per request in under 5ms at p99, and an immutable audit log that records what happened identically whether the actor was a person in the UI, a script on a laptop, or an agent working through MCP.

Platforms with two surfaces need two security models, and the informal one — the internal path the UI uses — is invariably the softer target. Platforms with one surface get agent-grade security almost for free, because there is exactly one place where authorization happens and exactly one shape of record to audit.

The screen is just one client. That sentence, taken seriously, reorganizes how enterprise software gets built — and it is the difference between a platform agents can operate and a platform agents can only watch.