API Surface

Summary

API Surface is the contract layer for HTTP services: OpenAPI, operation semantics, workflow descriptions, extensions, versioning, and event delivery. Use it when agents need to discover or generate calls against a web API without guessing from prose.

• Owns: HTTP APIs, OpenAPI 3.1/3.2, Arazzo workflows, webhooks, API versioning, and machine-readable service contracts.
• Does not own: cross-framework tool registry design; see Tool Design. MCP protocol servers; see MCP Servers.
• Agent-ready means: complete schemas, stable operation IDs, explicit safety/idempotency semantics, structured errors, and versioned behavior.

Start Here

1. OpenAPI for Agents - Make the API spec the source of truth for agent calls.
2. Tool Definitions - Translate HTTP operations into clear generated tools.
3. Arazzo Workflows - Document multi-step API sequences agents should not infer.
4. OpenAPI Extensions - Add agent-facing metadata without breaking the base contract.
5. API Versioning - Keep agents pinned to stable behavior.
6. Webhooks and Events - Expose asynchronous state changes agents can react to.

Related

1. Tool Design - Hand-authored or framework-portable tool definitions.
2. MCP Servers - Protocol-specific exposure of tools, resources, and prompts.
3. Error Handling - Problem Details and retry guidance for API failures.
4. Authentication - Credentials, scopes, and delegated access for agent callers.
5. Discovery - Public routes that help agents find API specs and catalogs.

Retrieval and lifecycle behavior

Retrieval and Job Contracts covers REST and GraphQL pagination, asynchronous jobs, bulk operations, partial errors, schema completeness, and client compatibility.