The new way to API.

OpenAPI Extensions

Table Of Contents

AgenticAPI leverages OpenAPI extensions to enhance semantic discoverability, enabling AI agents to understand and invoke action-oriented verbs dynamically. These extensions annotate endpoints with metadata about verbs, categories, parameter impacts, and compatibility, reducing reliance on external documentation. This document details the key extensions (x-action, x-intent-impact, etc.) and provides an example OpenAPI YAML snippet.

Key Extensions #

  • x-action: Specifies the action verb (e.g., summarize, fetch), identifying the task’s intent.
  • x-category: Indicates the verb’s category (e.g., Compute, Acquire), aligning with the ACTION framework.
  • x-intent-impact: Describes how parameters affect the action (e.g., format=bullets changes response structure).
  • x-preconditions: Lists requirements for execution (e.g., valid document_id).
  • x-alias-for: Maps action verbs to REST endpoints for compatibility (e.g., POST /document → SUMMARIZE /document).
  • x-side-effects (planned for v0.4.0): Lists potential impacts (e.g., database updates, notifications).
  • x-intent-weighting (planned for v0.4.0): Quantifies cost, priority, and risk for action selection.

These extensions are embedded in OpenAPI schemas, accessible via /openapi.json or a planned DISCOVER /actions endpoint.

Example: OpenAPI with Extensions #

The following OpenAPI YAML snippet demonstrates extensions for the SUMMARIZE and NOTIFY verbs, including current and planned metadata.

YAML
openapi: 3.0.3
info:
  title: AgenticAPI
  version: 0.3.0
paths:
  /document:
    summarize:
      x-action: summarize
      x-category: compute
      x-intent-impact:
        format: Changes response structure (text or bullets)
        max_words: Limits summary length
        style: Adjusts tone (neutral, formal, casual)
      x-preconditions: Valid document_id required
      summary: Summarize a document
      operationId: summarizeDocument
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                document_id:
                  type: string
                format:
                  type: string
                  enum: [text, bullets]
                  default: text
                max_words:
                  type: integer
                  default: 50
                style:
                  type: string
                  enum: [neutral, formal, casual]
                  default: neutral
                output_format:
                  type: string
                  enum: [json, text]
                  default: json
              required: [document_id]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      summary:
                        type: string
                      title:
                        type: string
                  used_fallback:
                    type: boolean
      x-intent-weighting:  # Planned for v0.4.0
        priority: high
        cost_estimate: 0.01
        risk_profile: low
        execution_time: 2.0
    post:
      summary: Summarize a document (POST alias)
      operationId: summarizeDocumentPost
      x-alias-for: SUMMARIZE /document
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SummarizeQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummarizeResponse'
  /notify:
    notify:
      x-action: notify
      x-category: communicate
      x-intent-impact:
        channel: Determines delivery method (email, sms)
        priority: Affects delivery urgency
      x-preconditions: Valid recipient required
      summary: Send a notification
      operationId: notifyUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                recipient:
                  type: string
                message:
                  type: string
                channel:
                  type: string
                  enum: [email, sms]
                  default: email
                priority:
                  type: string
                  enum: [normal, high]
                  default: normal
                output_format:
                  type: string
                  enum: [json, text]
                  default: json
              required: [recipient, message]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      status:
                        type: string
                      recipient:
                        type: string
                      message:
                        type: string
                  used_fallback:
                    type: boolean
      x-intent-weighting:  # Planned for v0.4.0
        priority: medium
        cost_estimate: 0.005
        risk_profile: low
        execution_time: 1.0
components:
  schemas:
    SummarizeQuery:
      type: object
      properties:
        document_id:
          type: string
        format:
          type: string
        max_words:
          type: integer
        style:
          type: string
        output_format:
          type: string
      required: [document_id]
    SummarizeResponse:
      type: object
      properties:
        result:
          type: object
          properties:
            summary:
              type: string
            title:
              type: string
        used_fallback:
          type: boolean
  • x-action: Identifies verbs (summarize, notify).
  • x-category: Specifies categories (compute, communicate).
  • x-intent-impact: Clarifies parameter effects (e.g., format, channel).
  • x-preconditions: Lists requirements (e.g., valid document_id).
  • x-alias-for: Maps POST /document to SUMMARIZE /document.
  • x-intent-weighting: Planned for v0.4.0, adding cost and priority metadata.

Benefits #

  • Agent Discoverability: Extensions enable agents to explore capabilities dynamically.
  • Developer Clarity: Metadata documents intent and constraints.
  • Compatibility: x-alias-for supports REST integration.
  • Future-Proofing: Planned extensions (x-intent-weighting) enhance optimization.

Best Practices #

  • Annotate All Endpoints: Include x-action and x-category for every verb.
  • Detail Impacts: Use x-intent-impact to explain parameter effects.
  • Plan for v0.4.0: Prepare for x-intent-weighting and x-side-effects.

Next Steps #

What are your feelings
Updated on May 29, 2025