The contract

Forty-six operations, one machine-readable schema, three transports that honor it identically. krabs is the contract.

The five properties

Every operation in krabs honors the same five properties. The transports differ in wire format; the guarantees do not.

• Intent — every endpoint is a verb-noun, e.g. contact.upsert. CRUD verbs from HTTP never leak into the model. The agent picks an operation by name, not by method.
• Idempotency — every mutation accepts an Idempotency-Key. Replaying the same key returns the same result without a second write. Retries are safe by default.
• Dry-run — every mutation accepts --dry-run on the CLI or dry_run: true on MCP and HTTP. The response describes the plan: the records that would be touched, the diff that would be written, the audit row that would land. Nothing is persisted.
• Schema introspection — GET /v1/schema returns the full contract: every operation, every argument, every error code. The agent reads its own manual. No SDK is required.
• Reversible audit — every write lands in an append-only log. The destructive ones (contact.delete, deal.delete, etc.) return an undo_token valid for 24 hours. One call rolls the row back.

The 46 operations

Seven primitive nouns plus agent and account, totaling forty-six verbs.

Reading the schema

The schema is one JSON document. Agents read it on connect; humans curl it.

curl https://$KRABS_TOKEN@api.krabs.dev/v1/schema | jq '.operations | keys[]'

Truncated output:

"account.audit"
"account.usage"
"agent.list"
"agent.register"
"agent.revoke"
"contact.delete"
"contact.get"
"contact.list"
"contact.merge"
"contact.search"
"contact.tag"
"contact.untag"
"contact.upsert"
"deal.advance"
"deal.close"
…

Each entry resolves to a typed argument schema, a typed return schema, the full set of error codes it can raise, and links to the relevant audit events.

Versioning

v1 is stable. Breaking changes ship under v2 with a six-month overlap window during which both versions remain reachable on the same domains. Additive changes — new operations, new optional fields, new error codes — ship in v1.x without notice.

The schema document carries a version field and a per-operation added_in marker. Agents written against v1.0 keep working against v1.7.

Compliance tests

Every transport publishes a compliance test suite as part of its release. The suite exercises all five properties against a live endpoint and asserts conformance.

Anyone can plug their own agent host into the suite and verify it speaks the contract faithfully. The same suite runs in krabs’s own CI on every commit. A transport that fails compliance does not ship.

/v1/schema → Runs & SSE → Webhooks →