Design an API contract

Describe your API in plain words, and your agent writes a contract: a machine-readable description of what it accepts and returns.

Write the API contract

To get an OpenAPI 3.1 contract for an API you own, ask:

Use api-contract to generate an OpenAPI contract for an order-management service: create an order, fetch it, list a customer's orders, cancel one.

The api-contract skill designs the URLs, payloads, errors, and security, and checks the result against the design standard before showing it. The standard is Zalando’s by default, or your organization’s own if you plugged one in. Hand it a partial OpenAPI file and it fills the gaps instead of starting over.

Write an event contract

Events are messages you publish, such as an order placed. When your feature owns the event, ask:

Use event-contract to author the AsyncAPI contract for the order events we publish: order.placed, order.cancelled. Order is the resource we own.

The event-contract skill writes an AsyncAPI document in contracts/asyncapi/, with channels, messages, and payload schemas, using CloudEvents envelopes by default.

Write contracts only for what you own

If you only consume an API or an event, point to the owner’s contract and write none, because a contract you author for someone else’s API drifts from the real one. If the event’s contract already sits in contracts/asyncapi/, reference it. If its producer is outside your repository, note the type you depend on and write nothing.

Next, write a spec that the build follows and tests against this contract.