Semantic Extensions for Agent APIs

┌──────────┬─────────────────────────────────┐
│ 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             │
└──────────┴─────────────────────────────────┘

paths:
  /orders/{id}:
    get:
      operationId: get_order
      x-action: Acquire
      x-category: orders
      summary: Get an order by ID

  /orders:
    post:
      operationId: create_order
      x-action: Transact
      x-category: orders
      summary: Create a new order

  /reports/generate:
    post:
      operationId: generate_sales_report
      x-action: Compute
      x-category: reporting
      summary: Generate a sales report for a date range

  /deployments:
    post:
      operationId: trigger_deployment
      x-action: Orchestrate
      x-category: infrastructure
      summary: Trigger a production deployment

  /notifications/send:
    post:
      operationId: send_notification
      x-action: Notify
      x-category: communications
      summary: Send a push notification to a user

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

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.

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.

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.

paths:
  /internal/debug/state:
    get:
      operationId: get_debug_state
      x-speakeasy-mcp:
        ignored: true   # Do not generate an MCP tool for this endpoint

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]

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.

x-speakeasy-mcp:
  scopes:
    read:
      operations:
        - method: GET
    write:
      operations:
        - method: POST
        - method: PUT
        - method: PATCH
    admin:
      operations:
        - path-pattern: /admin/*
        - path-pattern: /internal/*

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.

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 representation of an operation
POST /orders create_order "Creates a new order for the authenticated user"
  body: {product_ids: string[], quantity: integer, shipping_address_id: uuid}
  req: [product_ids, quantity]
  200: {id: uuid, status: string, total: number, created_at: date-time}
  400: "Invalid product ID or insufficient stock"
  422: "Shipping address not found"