Blog ← All posts

The wire protocol is the product

Why Cuitty's HTTP wire protocol — not the TypeScript SDK, not the Python client, not the admin UI — is the real contract.

By Cuitty Engineering
  • engineering
  • protocol
  • design

Every module in Cuitty exposes the same surface: a JSON-over-HTTP API, schema-stable across minor versions, with consistent error shapes and a consistent pagination dialect. That API is the contract. The SDKs are conveniences.

This is not a stylistic preference. It is the only design that lets us simultaneously serve human operators, IDE extensions, CI bots, language SDKs we have not written yet, and AI agents — without forking the platform for each of them.

Why thin SDKs

A thick SDK is a second product. It gains its own bugs, its own release cycle, its own version skew, and — the killer — its own opinions that quietly drift from the server’s. We have all watched a Python client implement a retry policy the Node client does not. We do not want to maintain that universe.

Cuitty’s TypeScript SDK is generated from an OpenAPI spec. The Python SDK is generated from the same spec. The Go SDK, when we ship it, will be too. If a behavior matters, it lives on the server and the spec describes it. If it does not matter enough to be in the spec, it does not belong in an SDK.

What lives at the wire

A few things are non-negotiable at the protocol layer:

  • Idempotency keys on all mutating endpoints. The server deduplicates; the SDK does not retry blindly.
  • Cursor pagination with opaque tokens. No offset/limit anywhere.
  • Structured errors — every 4xx/5xx response has { code, message, details, requestId }. Strings in message are for humans; agents key off code.
  • Server-Timing headers on every response, so the SDK never has to guess what the slow part was.

If you can curl it, you can drive it. That is the test.

Why this matters for agents

Agent platforms are SDK-shaped only by accident. What an agent actually wants is a typed schema, deterministic errors, and the ability to replay a request. A wire-protocol-first design gives all three for free. Our /agents page lays out the agent contract in detail.

The cost we accept

Wire-first means the SDK cannot smooth over a server bug. If the API surfaces something awkwardly, every consumer feels it. We treat that as a forcing function rather than a problem. The protocol gets refined; the SDKs follow.