Introduction

An API is a promise. Once a human, an agent, or another service depends on the shape of your surface, that shape is a contract you have to honor. Cogitave takes two questions that most teams blur together and gives each its own standard: how a contract is shaped, and how a contract changes over time.

• The API design standard owns the shape - resource modeling, naming, standard methods, the error model, pagination, idempotency. It says what a good v1 looks like.
• The versioning-and-deprecation standard owns the evolution - how that same contract is versioned, deprecated, sunset, and retired. It says how a shape changes without breaking anyone.

The two are read together and deliberately never restate each other. The design standard is settled by ADR-0019 and the versioning standard by ADR-0015, which together fix the interface layer for the whole estate before the first surface ships.

Why one shape, four protocols

Cogitave is MCP-native and also speaks HTTP, gRPC, and GraphQL. The design standard's core bet is that a single concept has one shape across all four: same field names, same enum values, same error taxonomy, same pagination contract. That is what lets an agent or an auditor read one model instead of four - and what stops an AI from re-deriving a surface that already exists.

What you will get from this module

Not a REST-versus-gRPC debate - a working command of the conventions you apply to design a clean surface, the handful of MUST invariants you can never deviate from, and the discipline to evolve that surface additively so a live consumer is never broken without consent.