--- title: "OpenAPI Extensions" description: "OpenAPI extensions, semantic taxonomies, and tooling for enriching your API with agent-specific behavioral hints" url: "https://agentsurface.dev/docs/api-surface/openapi-extensions" lastVerified: 2026-09-24 lastModified: 2026-09-25T05:46:01.000Z --- ## Summary [#summary] OpenAPI extensions like x-action and x-category add semantic metadata to operations. The AgenticAPI ACTION taxonomy classifies operations into six categories: Acquire (read), Compute (transform), Transact (create/modify), Integrate (sync), Orchestrate (multi-step), and Notify (communicate). This enables agents to make safer routing decisions. ``` ┌──────────┬─────────────────────────────────┐ │ Category │ Description │ ├──────────┼─────────────────────────────────┤ │ Acquire │ Read data without side effects │ │ Compute │ Transform or analyze data │ │ Transact │ Create or modify records │ │ Integrate│ Connect with external systems │ │ Orchestrate│ Trigger multi-step processes │ │ Notify │ Send communications │ └──────────┴─────────────────────────────────┘ ``` Standard OpenAPI covers what your API does. Extensions tell agents how to behave when using it - which operations need confirmation before execution, which are safe to retry, which are destructive, and what category each operation belongs to. This page covers the extension ecosystem and the tooling built on top of it. ## The AgenticAPI ACTION Taxonomy [#the-agenticapi-action-taxonomy] The AgenticAPI project defines six action categories (the ACTION taxonomy) for classifying API operations by what kind of effect they have. These categories help agents reason about risk, sequencing, and reversibility without reading the full operation description. | Category | Code | Description | Examples | | ----------- | ---- | ------------------------------------- | ------------------------------------------------------- | | Acquire | A | Read data without side effects | `get_user`, `list_orders`, `search_products` | | Compute | C | Transform or analyze data | `calculate_tax`, `generate_report`, `validate_address` | | Transact | T | Create or modify records | `create_order`, `update_profile`, `process_payment` | | Integrate | I | Connect or sync with external systems | `sync_contacts`, `import_csv`, `webhook_register` | | Orchestrate | O | Trigger multi-step processes | `run_pipeline`, `kick_off_workflow`, `deploy_release` | | Notify | N | Send communications | `send_email`, `post_slack_message`, `push_notification` | ### `x-action` and `x-category` Extensions [#x-action-and-x-category-extensions] Apply these extensions at the operation level: ```yaml paths: /orders/{id}: get: operationId: get_order x-action: get_order x-category: Acquire summary: Get an order by ID /orders: post: operationId: create_order x-action: create_order x-category: Transact summary: Create a new order /reports/generate: post: operationId: generate_sales_report x-action: generate_sales_report x-category: Compute summary: Generate a sales report for a date range /deployments: post: operationId: trigger_deployment x-action: trigger_deployment x-category: Orchestrate summary: Trigger a production deployment /notifications/send: post: operationId: send_notification x-action: send_notification x-category: Notify summary: Send a push notification to a user ``` Agent frameworks that understand the ACTION taxonomy can apply category-level policies: for example, requiring human confirmation for all `Transact` and `Orchestrate` operations, or rate-limiting `Notify` operations to prevent spam. ## Agent Behavioral Extensions [#agent-behavioral-extensions] ### `x-agent-requires-confirmation` [#x-agent-requires-confirmation] Marks operations that should pause for human approval before the agent executes them. This is framework-independent - any agent framework that respects this extension will surface a confirmation prompt. ```yaml paths: /accounts/{id}: delete: operationId: delete_account x-agent-requires-confirmation: true description: Permanently deletes an account and all associated data /billing/charge: post: operationId: process_payment x-agent-requires-confirmation: true description: Charges the customer's payment method /users/{id}/password-reset: post: operationId: force_password_reset x-agent-requires-confirmation: true description: Forces a password reset for the specified user ``` ### `x-agent-idempotent` [#x-agent-idempotent] Signals that the operation can be called multiple times with the same inputs and will produce the same result. Agents use this to decide whether retrying a failed call is safe. ```yaml paths: /orders/{id}/confirm: post: operationId: confirm_order x-agent-idempotent: true description: > Confirms an order. Idempotent: calling this multiple times on the same order will not create duplicate confirmations. /webhooks/register: put: operationId: register_webhook x-agent-idempotent: true description: > Registers or updates a webhook endpoint. Using PUT semantics makes this safe to call multiple times without creating duplicate registrations. ``` ### `x-agent-destructive` [#x-agent-destructive] Marks operations that permanently delete data or make irreversible changes. Agents can surface this to users or require additional confirmation beyond what `x-agent-requires-confirmation` provides. ```yaml paths: /projects/{id}: delete: operationId: delete_project x-agent-destructive: true x-agent-requires-confirmation: true description: Permanently deletes a project and all contained resources /database/truncate: post: operationId: truncate_table x-agent-destructive: true x-agent-requires-confirmation: true description: Removes all rows from the specified table. Cannot be undone. ``` ## Speakeasy MCP Extension [#speakeasy-mcp-extension] Speakeasy provides `x-speakeasy-mcp` for customizing how MCP tool generation treats individual operations. ### Tool Name Override [#tool-name-override] ```yaml paths: /v2/users/{user_id}/profile: get: operationId: v2_get_user_profile_by_id x-speakeasy-mcp: tool-name: get_user_profile description: > Get the full profile for a user. Use when you have the user's ID and need their complete profile data including settings and preferences. ``` ### Excluding Operations from MCP Generation [#excluding-operations-from-mcp-generation] ```yaml paths: /internal/debug/state: get: operationId: get_debug_state x-speakeasy-mcp: ignored: true # Do not generate an MCP tool for this endpoint ``` ### Grouping Tools by Scope [#grouping-tools-by-scope] ```yaml paths: /users: get: operationId: list_users x-speakeasy-mcp: scopes: [user-management, admin] /analytics/events: get: operationId: list_events x-speakeasy-mcp: scopes: [analytics, reporting] ``` Agent frameworks can then load only the tools for the scopes relevant to the current agent session, keeping the active tool count low. ### Overriding Parameter Descriptions [#overriding-parameter-descriptions] ```yaml paths: /orders: get: operationId: list_orders parameters: - name: status in: query schema: type: string enum: [pending, processing, completed, cancelled] x-speakeasy-mcp: description: > Filter orders by current status. Use "pending" to find orders awaiting processing. Use "completed" for fulfilled orders. Omit to return all orders regardless of status. ``` ## Pattern-Based Scope Mapping [#pattern-based-scope-mapping] Rather than annotating every operation individually, define scope patterns that apply to operations matching path or method patterns: ```yaml x-speakeasy-mcp: scopes: read: operations: - method: GET write: operations: - method: POST - method: PUT - method: PATCH admin: operations: - path-pattern: /admin/* - path-pattern: /internal/* ``` This lets you partition a large API into read-only, read-write, and admin subsets for different agent permission levels. ## Amazon Bedrock `x-requireConfirmation` [#amazon-bedrock-x-requireconfirmation] Bedrock Agents uses its own extension for confirmation requirements. Apply it at the operation level in OpenAPI specs used with Bedrock action groups: ```yaml paths: /funds/transfer: post: operationId: transfer_funds x-amazon-apigateway-integration: # ... integration config x-requireConfirmation: ENABLED description: > Transfers funds between accounts. Requires human confirmation before execution due to financial impact. ``` Valid values: `ENABLED` (require confirmation) and `DISABLED` (default, no confirmation required). ## Discovery Endpoint: `GET /actions` [#discovery-endpoint-get-actions] Publishing a discovery endpoint lets agents find your action catalog without reading the full OpenAPI spec. There's no standardized HTTP method or path for this - OpenAPI 3.2 added a new `QUERY` method, but nothing called `DISCOVER`. A plain `GET` at a well-known path works and needs no special client support: ```yaml paths: /actions: get: operationId: discover_actions summary: List available agent-ready actions description: > Returns the catalog of operations available to agents, grouped by category. Agents can call this to understand what capabilities are available before selecting specific tools. responses: "200": content: application/json: schema: type: object properties: actions: type: array items: type: object properties: operationId: type: string summary: type: string category: type: string enum: [Acquire, Compute, Transact, Integrate, Orchestrate, Notify] requiresConfirmation: type: boolean isDestructive: type: boolean example: actions: - operationId: get_order summary: Get an order by ID category: Acquire requiresConfirmation: false isDestructive: false - operationId: delete_order summary: Permanently delete an order category: Transact requiresConfirmation: true isDestructive: true ``` ## LAPIS Format [#lapis-format] [LAPIS](https://github.com/cr0hn/LAPIS) (Lightweight API Specification for Intelligent Systems) is a compact representation format for OpenAPI specs, designed for LLM context windows. Benchmarked against five production API specs (including GitHub and Twilio), it averages an 85.5% token reduction compared to standard OpenAPI YAML while retaining the information agents need to select and call operations. A full OpenAPI spec in YAML might be 50,000 tokens. The same spec in LAPIS format is typically well under 10,000 tokens. This matters when you are stuffing tool definitions into a model context window. ``` create_order POST /orders Creates a new order for the authenticated user. > product_ids: [str] > quantity: int > shipping_address_id?: uuid < Order ``` LAPIS is useful for: * Injecting API context into agent prompts without exhausting the context window * Pre-processing specs before tool generation * Building lightweight tool-picker prompts ## Auto-Generating MCP from OpenAPI [#auto-generating-mcp-from-openapi] The extensions above - especially `x-speakeasy-mcp` - feed directly into tools that generate MCP servers from your OpenAPI spec. Generation is only a starting point: a naive 1:1 mapping produces 50–300 tools that overwhelm agents, with descriptions written for human developers rather than agent reasoning. The correct workflow is generate → prune → rewrite → add composites, targeting 10–20 tools per domain. For the full generator comparison (Stainless, Speakeasy, FastMCP, openapi-mcp-generator), the hybrid workflow step-by-step, and the reasoning behind not shipping generated output directly, see [Auto-Generating MCP from OpenAPI](/docs/mcp-servers/auto-generation). This page owns the extension mapping that those generators consume; that page owns the generation workflow. ## Checklist [#checklist] * [ ] Operations are categorized with `x-category` using the ACTION taxonomy * [ ] Destructive operations have `x-agent-destructive: true` * [ ] Irreversible operations have `x-agent-requires-confirmation: true` * [ ] Idempotent operations are marked with `x-agent-idempotent: true` * [ ] MCP tool count per agent session is under 20 after pruning * [ ] Auto-generated tool descriptions have been rewritten as agent trigger conditions * [ ] Composite tools exist for common multi-step sequences * [ ] `x-speakeasy-mcp: ignored: true` is set on internal/debug endpoints ## Related Pages [#related-pages] * [OpenAPI for Agents](./openapi-for-agents) - the base spec design that extensions annotate * [Tool Definitions](./tool-definitions) - how extensions translate into MCP annotations * [Arazzo Workflows](./arazzo-workflows) - composite workflows as an alternative to composite tools