AgenticAPI’s semantic discoverability enables AI agents to dynamically explore and invoke API capabilities without relying on external documentation or natural language prompts. By leveraging OpenAPI extensions, AgenticAPI makes endpoints machine-readable, allowing agents to understand verbs, categories, and constraints. This document explains how discoverability works and provides an example of a planned DISCOVER /actions endpoint.

OpenAPI Extensions #

AgenticAPI uses custom OpenAPI extensions to annotate endpoints with metadata:

• x-action: Specifies the action verb (e.g., summarize, fetch).
• x-category: Indicates the verb category (e.g., Compute, Acquire).
• x-intent-impact: Describes parameter effects (e.g., format=bullets changes response).
• x-preconditions: Lists requirements (e.g., valid document_id).
• x-alias-for: Maps action verbs to REST endpoints for compatibility.

These extensions ensure agents can reason about API capabilities programmatically.

DISCOVER /actions Endpoint (Planned) #

The DISCOVER /actions endpoint (planned for future releases) will return a list of available actions, their categories, and constraints, enabling agents to query the API’s functionality dynamically.

Example Response:

{
  "actions": [
    {
      "action_verb": "summarize",
      "category": "Compute",
      "path": "/document",
      "scopes_required": ["data:read"],
      "preconditions": "Valid document_id",
      "x-intent-impact": {
        "format": "Changes response structure (text or bullets)",
        "max_words": "Limits summary length"
      }
    },
    {
      "action_verb": "fetch",
      "category": "Acquire",
      "path": "/fetch",
      "scopes_required": ["data:read"],
      "preconditions": "Valid document_id"
    },
    {
      "action_verb": "notify",
      "category": "Communicate",
      "path": "/notify",
      "scopes_required": ["notify:send"],
      "preconditions": "Valid recipient"
    }
  ]
}

• action_verb: The custom verb (e.g., summarize).
• category: The verb’s category (e.g., Compute).
• path: The endpoint URL.
• scopes_required: Security scopes (planned for OAuth2 integration).
• preconditions: Prerequisites for execution.
• x-intent-impact: Parameter effects for agent reasoning.

Until DISCOVER /actions is implemented, agents can use the OpenAPI schema (available at /docs or /openapi.json) to explore endpoints and extensions.

Benefits #

• Agent Autonomy: Agents can discover actions without human intervention.
• Reduced Documentation Dependency: OpenAPI extensions provide machine-readable metadata.
• Dynamic Adaptation: Agents can adjust to new verbs or endpoints as APIs evolve.

Best Practices #

• Annotate All Endpoints: Include x-action and x-category in OpenAPI definitions.
• Clarify Constraints: Use x-preconditions to prevent invalid requests.
• Plan for Discoverability: Prepare for DISCOVER /actions in future designs.

Next Steps #

• Learn about ACTION Verbs for verb details.
• Explore Payloads and Parameters for input design.
• Try Implementing Custom Verbs to extend the API.