---
title: "API Surface"
description: "HTTP, OpenAPI, and service contracts that agents can discover and call reliably"
url: "https://agentsurface.dev/docs/api-surface"
lastVerified: 2026-09-24
lastModified: 2026-09-25T09:21:34.000Z
---



## Summary [#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](/docs/tool-design). MCP protocol servers; see [MCP Servers](/docs/mcp-servers).
* **Agent-ready means:** complete schemas, stable operation IDs, explicit safety/idempotency semantics, structured errors, and versioned behavior.

## Start Here [#start-here]

* [OpenAPI for Agents](/docs/api-surface/openapi-for-agents) - Make the API spec the source of truth for agent calls.
* [Tool Definitions](/docs/api-surface/tool-definitions) - Translate HTTP operations into clear generated tools.
* [Arazzo Workflows](/docs/api-surface/arazzo-workflows) - Document multi-step API sequences agents should not infer.
* [OpenAPI Extensions](/docs/api-surface/openapi-extensions) - Add agent-facing metadata without breaking the base contract.
* [API Versioning](/docs/api-surface/api-versioning) - Keep agents pinned to stable behavior.
* [Webhooks and Events](/docs/api-surface/webhooks-events) - Expose asynchronous state changes agents can react to.

## Related [#related]

* [Tool Design](/docs/tool-design) - Hand-authored or framework-portable tool definitions.
* [MCP Servers](/docs/mcp-servers) - Protocol-specific exposure of tools, resources, and prompts.
* [Error Handling](/docs/error-handling) - Problem Details and retry guidance for API failures.
* [Authentication](/docs/authentication) - Credentials, scopes, and delegated access for agent callers.
* [Discovery](/docs/discovery) - Public routes that help agents find API specs and catalogs.

## Retrieval and lifecycle behavior [#retrieval-and-lifecycle-behavior]

[Retrieval and Job Contracts](/docs/api-surface/retrieval-and-job-contracts) covers REST and GraphQL pagination, asynchronous jobs, bulk operations, partial errors, schema completeness, and client compatibility.