openapi: 3.0.3
info:
  title: n3 Agent Server API
  description: >-
    Localhost-only HTTP API for agent and client development.


    **Important:** v1 has no bearer token protection. Access is limited to `127.0.0.1` only.


    ## Response Envelopes


    ### Read Success

    ```json

    {"ok":true,"status":"ok","data":{}}

    ```


    ### Write Success/Failure

    ```json

    {"ok":true,"status":"SUCCESS","message":"Queued dialog continue","result":{"status":"SUCCESS"}}

    ```


    ### Errors

    ```json

    {"ok":false,"status":"PACED","message":"Action pacing is active"}

    ```


    ## Request Handling


    - Read endpoints snapshot live client state on the RuneLite client thread

    - Gameplay write endpoints route through `InteractionApi.actions.*` and return `InteractionResult`-backed JSON

    - Clients must avoid tight retry loops; treat `PACED` and failure responses as pacing signals

    - Plugin operations are limited to configured allowlist and refuse required shared plugins (e.g.,
    `PacketUtilsPlugin`)
  version: 1.0.0
  contact:
    name: n3 Plugins
  license:
    name: MIT
servers:
  - url: 'http://127.0.0.1:17631'
    description: Default local binding
tags:
  - name: State
    description: Query client state (read-only)
  - name: Widgets
    description: Widget inspection and interaction
  - name: Scene
    description: 'Scene objects, NPCs, items, and players'
  - name: Inventory
    description: Inventory manipulation
  - name: Bank
    description: Bank operations
  - name: Dialogue
    description: Dialogue interaction
  - name: Movement
    description: Player movement and walking
  - name: Skills
    description: Skill inspection
  - name: Items
    description: Item-based interactions
  - name: Plugins
    description: Plugin enable/disable
  - name: Inspection
    description: Game state inspection
  - name: MCP
    description: Model Context Protocol endpoint
  - name: Login
    description: Memory-only dashboard login profile operations
paths:
  /api/v1/stream/status:
    get:
      tags: [State]
      summary: Get dashboard stream configuration
      responses: {'200': {description: Stream configuration}}
  /api/v1/navigation/status:
    get:
      tags: [Movement]
      summary: Get current navigation status
      responses: {'200': {description: Navigation status}}
  /api/v1/navigation/preview:
    post:
      tags: [Movement]
      summary: Preview a path without starting movement
      responses: {'200': {description: Path preview}}
  /api/v1/login/modes:
    get:
      tags: [Login]
      summary: List supported login modes
      responses: {'200': {description: Supported login modes}}
  /api/v1/login/status:
    get:
      tags: [Login]
      summary: Get memory-only login profile status
      responses: {'200': {description: Login profile status without secrets}}
  /api/v1/login/profile/apply:
    post:
      tags: [Login]
      summary: Apply a memory-only login profile
      responses: {'200': {description: Updated login profile status}}
  /api/v1/login/start:
    post:
      tags: [Login]
      summary: Start login with the applied profile
      responses: {'200': {description: Login initiation status}}
  /api/v1/login/clear:
    post:
      tags: [Login]
      summary: Clear the memory-only login profile
      responses: {'200': {description: Cleared login profile status}}
  /api/v1/state:
    get:
      tags:
        - State
      summary: Get current game state snapshot
      description: >-
        Returns a comprehensive snapshot of the current client state including position, animation, game state, and
        other metadata
      operationId: getState
      responses:
        '200':
          description: State snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
              example:
                ok: true
                status: ok
                data:
                  plane: 0
                  x: 3222
                  'y': 3222
  /api/v1/widgets/list:
    get:
      tags:
        - Widgets
      summary: List all widgets
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 1000
          description: Maximum number of widgets to return
      responses:
        '200':
          description: List of widgets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/widgets/search:
    get:
      tags:
        - Widgets
      summary: Search widgets by text and action
      parameters:
        - name: text
          in: query
          schema:
            type: string
          description: Widget text to search for (case-insensitive substring match)
        - name: action
          in: query
          schema:
            type: string
          description: Action name to filter by
        - name: limit
          in: query
          schema:
            type: integer
            default: 1000
          description: Maximum number of results
      responses:
        '200':
          description: Matching widgets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/widgets/describe:
    get:
      tags:
        - Widgets
      summary: Get detailed widget information
      parameters:
        - name: widgetId
          in: query
          required: true
          schema:
            type: integer
          description: Widget ID (pack and child format)
        - name: id
          in: query
          schema:
            type: integer
          description: Alternative parameter name for widgetId
      responses:
        '200':
          description: Widget description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/widgets/click:
    post:
      tags:
        - Widgets
      summary: Click a widget
      description: 'Click a specific widget by ID, optionally specifying an action'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WidgetClickRequest'
      responses:
        '200':
          description: Click result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/inventory:
    get:
      tags:
        - Inventory
      summary: Get inventory items
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: Inventory items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/inventory/interact:
    post:
      tags:
        - Inventory
      summary: Interact with inventory item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryInteractRequest'
      responses:
        '200':
          description: Interaction result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/drop:
    post:
      tags:
        - Inventory
      summary: Drop inventory item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemIdentifier'
      responses:
        '200':
          description: Drop result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/players:
    get:
      tags:
        - Scene
      summary: Get visible players
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: List of visible players
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/npcs:
    get:
      tags:
        - Scene
      summary: Get visible NPCs
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: List of visible NPCs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/npcs/interact:
    post:
      tags:
        - Scene
      summary: Interact with NPC
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NPCInteractRequest'
      responses:
        '200':
          description: Interaction result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/objects:
    get:
      tags:
        - Scene
      summary: Get visible objects
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: List of visible objects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/objects/interact:
    post:
      tags:
        - Scene
      summary: Interact with scene object
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObjectInteractRequest'
      responses:
        '200':
          description: Interaction result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/ground-items:
    get:
      tags:
        - Scene
      summary: Get ground items
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: List of ground items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/ground-items/pickup:
    post:
      tags:
        - Scene
      summary: Pick up ground item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroundItemPickupRequest'
      responses:
        '200':
          description: Pickup result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/skills:
    get:
      tags:
        - Skills
      summary: Get skill levels and experience
      responses:
        '200':
          description: Skill data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/developer/metrics:
    get:
      tags:
        - State
      summary: Get a structured developer metrics snapshot
      description: >-
        Returns world, player position, skills, inventory, bank state, session/account metadata, and optional screenshot
        data for development telemetry.
      responses:
        '200':
          description: Developer metrics snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/developer/heartbeat:
    post:
      tags:
        - State
      summary: Publish a developer metrics heartbeat
      description: >-
        Publishes the current developer metrics snapshot to an optional webhook URL. Supports an optional secret and
        screenshot inclusion.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                webhookUrl:
                  type: string
                secret:
                  type: string
                includeScreenshot:
                  type: boolean
      responses:
        '200':
          description: Heartbeat delivery result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/bank/status:
    get:
      tags:
        - Bank
      summary: Get bank open/close status
      responses:
        '200':
          description: Bank status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/bank:
    get:
      tags:
        - Bank
      summary: Get bank item snapshot
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: Bank items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/bank/open:
    post:
      tags:
        - Bank
      summary: Open bank
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Open result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/deposit:
    post:
      tags:
        - Bank
      summary: Deposit item to bank
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ItemIdentifier'
                - type: object
                  properties:
                    amount:
                      type: integer
                      description: Amount to deposit
      responses:
        '200':
          description: Deposit result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/withdraw:
    post:
      tags:
        - Bank
      summary: Withdraw item from bank
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ItemIdentifier'
                - type: object
                  properties:
                    amount:
                      type: integer
                      description: Amount to withdraw
                    noted:
                      type: boolean
                      description: Whether to withdraw as noted
                  required:
                    - amount
      responses:
        '200':
          description: Withdraw result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/walk:
    post:
      tags:
        - Movement
      summary: Walk to destination
      description: >-
        Start or reuse a walker path to the specified coordinate. The endpoint is non-blocking; poll /api/v1/state for
        progress.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalkRequest'
      responses:
        '200':
          description: Walk started or canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/dialogue/continue:
    post:
      tags:
        - Dialogue
      summary: Continue dialogue
      description: Click the continue button in the current dialogue
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Continue result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/dialogue/select:
    post:
      tags:
        - Dialogue
      summary: Select dialogue option
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DialogueSelectRequest'
      responses:
        '200':
          description: Selection result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/use-item/item:
    post:
      tags:
        - Items
      summary: Use item on item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UseItemOnItemRequest'
      responses:
        '200':
          description: Interaction result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/use-item/npc:
    post:
      tags:
        - Items
      summary: Use item on NPC
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UseItemOnNPCRequest'
      responses:
        '200':
          description: Interaction result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/use-item/object:
    post:
      tags:
        - Items
      summary: Use item on object
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UseItemOnObjectRequest'
      responses:
        '200':
          description: Interaction result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/use-item/ground-item:
    post:
      tags:
        - Items
      summary: Use item on ground item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UseItemOnGroundItemRequest'
      responses:
        '200':
          description: Interaction result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/plugins:
    get:
      tags:
        - Plugins
      summary: List plugins
      responses:
        '200':
          description: Plugin list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/plugins/status:
    get:
      tags:
        - Plugins
      summary: Get plugin status (alias for /plugins)
      responses:
        '200':
          description: Plugin status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/plugins/enable:
    post:
      tags:
        - Plugins
      summary: Enable plugin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PluginOperationRequest'
      responses:
        '200':
          description: Enable result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/plugins/disable:
    post:
      tags:
        - Plugins
      summary: Disable plugin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PluginOperationRequest'
      responses:
        '200':
          description: Disable result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
  /api/v1/menu-entries:
    get:
      tags:
        - Inspection
      summary: Get visible menu entries
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: Menu entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/last-interactions:
    get:
      tags:
        - Inspection
      summary: Get last interactions
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: Last interactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/varbit:
    get:
      tags:
        - Inspection
      summary: Get varbit value
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: integer
          description: Varbit ID
      responses:
        '200':
          description: Varbit value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/varplayer:
    get:
      tags:
        - Inspection
      summary: Get varplayer value
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: integer
          description: Varplayer ID
      responses:
        '200':
          description: Varplayer value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /api/v1/varbit-changes:
    get:
      tags:
        - Inspection
      summary: Get recent varbit changes
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: Recent varbit changes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'
  /mcp:
    post:
      tags:
        - MCP
      summary: Model Context Protocol endpoint (non-SSE mode)
      description: |-
        Implements MCP Streamable HTTP in non-SSE mode for local agents.

        Supports: `initialize`, `ping`, `tools/list`, `tools/call`, `notifications/initialized`

        Returns JSON-RPC responses with `Content-Type: application/json`.
        Successful notifications return HTTP 202 with no body.
        Protocol failures return JSON-RPC errors.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: MCP JSON-RPC response
          content:
            application/json:
              schema:
                type: object
        '202':
          description: MCP notification accepted
        '405':
          description: GET method not allowed
  /api/v1/plugins/config:
    get:
      summary: GET /api/v1/plugins/config
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/plugins/configs:
    get:
      summary: GET /api/v1/plugins/configs
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/plugins/logs:
    get:
      summary: GET /api/v1/plugins/logs
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/suite/capabilities:
    get:
      summary: GET /api/v1/suite/capabilities
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/sdk/read:
    get:
      summary: GET /api/v1/sdk/read
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
    post:
      summary: POST /api/v1/sdk/read
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/world:
    get:
      summary: GET /api/v1/world
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/world-map:
    get:
      summary: GET /api/v1/world-map
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/camera:
    get:
      summary: GET /api/v1/camera
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/line-of-sight:
    get:
      summary: GET /api/v1/line-of-sight
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/item-metadata:
    get:
      summary: GET /api/v1/item-metadata
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/prices:
    get:
      summary: GET /api/v1/prices
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/social:
    get:
      summary: GET /api/v1/social
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/progress:
    get:
      summary: GET /api/v1/progress
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/recent-events:
    get:
      summary: GET /api/v1/recent-events
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/questhelper:
    get:
      summary: GET /api/v1/questhelper
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/production:
    get:
      summary: GET /api/v1/production
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/minigames:
    get:
      summary: GET /api/v1/minigames
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/loadout/state:
    get:
      summary: GET /api/v1/loadout/state
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/plugins/config/set:
    post:
      summary: POST /api/v1/plugins/config/set
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/plugins/config/unset:
    post:
      summary: POST /api/v1/plugins/config/unset
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/ge/open:
    post:
      summary: POST /api/v1/ge/open
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/ge/close:
    post:
      summary: POST /api/v1/ge/close
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/ge/collect:
    post:
      summary: POST /api/v1/ge/collect
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/ge/cancel:
    post:
      summary: POST /api/v1/ge/cancel
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/shop/buy:
    post:
      summary: POST /api/v1/shop/buy
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/trade/accept:
    post:
      summary: POST /api/v1/trade/accept
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/trade/decline:
    post:
      summary: POST /api/v1/trade/decline
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/trade/offer:
    post:
      summary: POST /api/v1/trade/offer
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/equipment/equip:
    post:
      summary: POST /api/v1/equipment/equip
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/equipment/unequip:
    post:
      summary: POST /api/v1/equipment/unequip
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/prayer/set:
    post:
      summary: POST /api/v1/prayer/set
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/prayer/set-only:
    post:
      summary: POST /api/v1/prayer/set-only
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/prayer/disable-all:
    post:
      summary: POST /api/v1/prayer/disable-all
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/prayer/quick-toggle:
    post:
      summary: POST /api/v1/prayer/quick-toggle
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/prayer/quick-open:
    post:
      summary: POST /api/v1/prayer/quick-open
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/prayer/quick-set:
    post:
      summary: POST /api/v1/prayer/quick-set
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/magic/cast:
    post:
      summary: POST /api/v1/magic/cast
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/magic/select:
    post:
      summary: POST /api/v1/magic/select
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/magic/deselect:
    post:
      summary: POST /api/v1/magic/deselect
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/combat/toggle-spec:
    post:
      summary: POST /api/v1/combat/toggle-spec
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/combat/set-attack-style:
    post:
      summary: POST /api/v1/combat/set-attack-style
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/combat/auto-retaliate:
    post:
      summary: POST /api/v1/combat/auto-retaliate
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/tab/open:
    post:
      summary: POST /api/v1/tab/open
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/production/choose:
    post:
      summary: POST /api/v1/production/choose
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/production/quantity:
    post:
      summary: POST /api/v1/production/quantity
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/production/amount:
    post:
      summary: POST /api/v1/production/amount
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/transport/travel:
    post:
      summary: POST /api/v1/transport/travel
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/deposit-box/deposit-all:
    post:
      summary: POST /api/v1/deposit-box/deposit-all
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/deposit-box/deposit-equipment:
    post:
      summary: POST /api/v1/deposit-box/deposit-equipment
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/deposit-box/deposit:
    post:
      summary: POST /api/v1/deposit-box/deposit
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/deposit-box/close:
    post:
      summary: POST /api/v1/deposit-box/close
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/bank-inventory/deposit:
    post:
      summary: POST /api/v1/bank-inventory/deposit
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/bank-worn-equipment/deposit-all:
    post:
      summary: POST /api/v1/bank-worn-equipment/deposit-all
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
  /api/v1/drop-pattern:
    post:
      summary: POST /api/v1/drop-pattern
      responses:
        '200':
          description: Agent Server JSON response
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    ReadResponse:
      type: object
      properties:
        ok:
          type: boolean
          example: true
        status:
          type: string
          enum:
            - ok
          example: ok
        data:
          type: object
          description: Response data (varies by endpoint)
      required:
        - ok
        - status
        - data
    InteractionResponse:
      type: object
      properties:
        ok:
          type: boolean
        status:
          type: string
          description: 'Interaction status (SUCCESS, PACED, FAILED, etc.)'
        message:
          type: string
          description: Human-readable message
        result:
          type: object
          properties:
            status:
              type: string
            message:
              type: string
            targetType:
              type: string
            targetName:
              type: string
            requestedAction:
              type: string
            actionIndex:
              type: integer
            availableActions:
              type: array
              items:
                type: string
      required:
        - ok
        - status
    ErrorResponse:
      type: object
      properties:
        ok:
          type: boolean
          example: false
        status:
          type: string
          example: invalid_request
        message:
          type: string
          example: Request could not be completed
        details:
          type: object
          description: Additional error details
      required:
        - ok
        - status
        - message
    ItemIdentifier:
      type: object
      description: 'Identify an item by name, ID, or inventory index'
      properties:
        name:
          type: string
          description: Item name (exact or mapped name)
        id:
          type: integer
          description: Item ID
        index:
          type: integer
          description: Inventory slot index (0-27)
      minProperties: 1
    ActionIdentifier:
      type: object
      description: Specify action by name or raw operation code
      properties:
        action:
          type: string
          description: 'Action name (e.g., "Use")'
        actions:
          type: array
          items:
            type: string
          description: Multiple action names to try in order
        op:
          type: integer
          description: Raw operation code (debugging escape hatch)
    WidgetClickRequest:
      allOf:
        - $ref: '#/components/schemas/ActionIdentifier'
        - type: object
          properties:
            widgetId:
              type: integer
              description: Widget ID in pack format
            index:
              type: integer
              description: Optional dynamic child index from widget list or search results
          required:
            - widgetId
    InventoryInteractRequest:
      allOf:
        - $ref: '#/components/schemas/ItemIdentifier'
        - $ref: '#/components/schemas/ActionIdentifier'
    NPCInteractRequest:
      type: object
      properties:
        name:
          type: string
          description: NPC name
        id:
          type: integer
          description: NPC ID
        index:
          type: integer
          description: NPC index
        action:
          type: string
          description: Action name
        actions:
          type: array
          items:
            type: string
          description: Multiple actions to try in order
      minProperties: 2
    ObjectInteractRequest:
      type: object
      properties:
        name:
          type: string
          description: Object name
        id:
          type: integer
          description: Object ID
        action:
          type: string
          description: Action name
        actions:
          type: array
          items:
            type: string
          description: Multiple actions to try in order
      minProperties: 2
    GroundItemPickupRequest:
      type: object
      properties:
        name:
          type: string
          description: Ground item name
        id:
          type: integer
          description: Ground item ID
        action:
          type: string
          description: Action name (typically "Take")
        actions:
          type: array
          items:
            type: string
          description: Multiple actions to try in order
      minProperties: 2
    WalkRequest:
      type: object
      properties:
        x:
          type: integer
          description: Destination X coordinate
        'y':
          type: integer
          description: Destination Y coordinate
        plane:
          type: integer
          description: Destination plane (default current)
        reachedDistance:
          type: integer
          description: Distance threshold for "reached" (default 2)
        cancelOnNewTarget:
          type: boolean
          description: Cancel path if new target set (default true)
        cancel:
          type: boolean
          description: Set to true to cancel active walk
      required:
        - x
        - 'y'
    DialogueSelectRequest:
      type: object
      properties:
        index:
          type: integer
          description: Dialogue option index (0-based)
        text:
          type: string
          description: Dialogue option text to match
    UseItemOnItemRequest:
      type: object
      properties:
        sourceId:
          type: integer
          description: Source item ID
        targetId:
          type: integer
          description: Target item ID
        sourceName:
          type: string
          description: Source item name
        targetName:
          type: string
          description: Target item name
      minProperties: 2
    UseItemOnNPCRequest:
      type: object
      properties:
        sourceId:
          type: integer
          description: Source item ID
        npcName:
          type: string
          description: Target NPC name
      required:
        - sourceId
        - npcName
    UseItemOnObjectRequest:
      type: object
      properties:
        sourceId:
          type: integer
          description: Source item ID
        sourceName:
          type: string
          description: Source item name
        objectName:
          type: string
          description: Target object name
      required:
        - objectName
    UseItemOnGroundItemRequest:
      type: object
      properties:
        sourceId:
          type: integer
          description: Source item ID
        groundItemId:
          type: integer
          description: Target ground item ID
      required:
        - sourceId
        - groundItemId
    PluginOperationRequest:
      type: object
      properties:
        className:
          type: string
          description: Plugin class name
        plugin:
          type: string
          description: Alternative parameter name for className
      minProperties: 1
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Endpoint not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    MethodNotAllowed:
      description: Method not allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'