openapi: 3.2.0
info:
  title: Powerduck protocol reference
  version: 1.0.0
  description: Official local-service example definitions. Start matching services separately.
servers:
  - url: 'http://127.0.0.1:8080'
tags:
  - name: http
  - name: sse
  - name: websocket
  - name: graphql
  - name: grpc
  - name: mcp
  - name: a2a
paths:
  /messages:
    post:
      operationId: create_message
      summary: create message
      description: >-
        Official Powerduck example definition. Replace the example endpoint with your own service
        before sending.
      tags:
        - http
      parameters:
        - name: X-Request-ID
          in: header
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - message
              properties:
                message:
                  type: string
                id:
                  type: string
            example:
              message: Hello
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                  id:
                    type: string
              example:
                message: Hello from Powerduck
                id: example-1
  /cache:
    additionalOperations:
      PURGE:
        operationId: purge_cache
        summary: purge cache
        description: >-
          Official Powerduck example definition. Replace the example endpoint with your own service
          before sending.
        tags:
          - http
        responses:
          '200':
            description: Successful response
            content:
              application/json:
                schema:
                  type: object
                  required:
                    - message
                  properties:
                    message:
                      type: string
                    id:
                      type: string
                example:
                  message: Hello from Powerduck
                  id: example-1
  /events:
    get:
      operationId: stream_events
      summary: stream events
      description: >-
        Official Powerduck example definition. Replace the example endpoint with your own service
        before sending.
      tags:
        - sse
      x-protocol: sse
      responses:
        '200':
          description: Server-sent events
          content:
            text/event-stream:
              itemSchema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                  id:
                    type: string
  /ws:
    get:
      operationId: chat_session
      summary: chat session
      description: >-
        Official Powerduck example definition. Replace the example endpoint with your own service
        before sending.
      tags:
        - websocket
      x-protocol: websocket
      x-session: true
      x-websocket:
        url: 'ws://127.0.0.1:8080/ws'
        subprotocols:
          - chat.v1
        headers: {}
        messages:
          - id: send-message
            name: Send message
            type: json
            body: '{"message":"Hello"}'
            requestSchema:
              type: object
              required:
                - message
              properties:
                message:
                  type: string
                id:
                  type: string
            responseSchema:
              type: object
              required:
                - message
              properties:
                message:
                  type: string
                id:
                  type: string
      responses:
        '101':
          description: Switching protocols. Message schemas are defined in x-websocket.messages.
  /graphql:
    post:
      operationId: get_message
      summary: get message
      description: >-
        Official Powerduck example definition. Replace the example endpoint with your own service
        before sending.
      tags:
        - graphql
      x-protocol: graphql
      x-graphql:
        endpoint: 'http://127.0.0.1:4000/graphql'
        query: 'query Message($id: ID!) { message(id: $id) { id message } }'
        operationName: Message
        variablesSchema:
          type: object
          required:
            - id
          properties:
            id:
              type: string
        variables:
          id: example-1
        responseSchema:
          type: object
          properties:
            data:
              type: object
              properties:
                message:
                  type: object
                  required:
                    - message
                  properties:
                    message:
                      type: string
                    id:
                      type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: object
                        required:
                          - message
                        properties:
                          message:
                            type: string
                          id:
                            type: string
              example:
                data:
                  message:
                    id: example-1
                    message: Hello
  /grpc/powerduck.examples.Echo/Echo:
    post:
      operationId: grpc_echo
      summary: grpc echo
      description: >-
        Official Powerduck example definition. Replace the example endpoint with your own service
        before sending.
      tags:
        - grpc
      x-protocol: grpc
      x-grpc:
        address: '127.0.0.1:50051'
        service: powerduck.examples.Echo
        method: Echo
        kind: unary
        reflection: false
        protoPaths:
          - ./echo.proto
        includeDirs:
          - .
        messages:
          - id: echo
            name: Echo
            type: json
            body: '{"message":"Hello"}'
            requestSchema:
              type: object
              required:
                - message
              properties:
                message:
                  type: string
                id:
                  type: string
            responseSchema:
              type: object
              required:
                - message
              properties:
                message:
                  type: string
                id:
                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                  id:
                    type: string
              example:
                message: Hello from Powerduck
                id: example-1
  /mcp/tools/echo:
    post:
      operationId: mcp_echo
      summary: mcp echo
      description: >-
        Official Powerduck example definition. Replace the example endpoint with your own service
        before sending.
      tags:
        - mcp
      x-protocol: mcp
      x-session: true
      x-mcp:
        endpoint: 'http://127.0.0.1:3000/mcp'
        transport: streamable-http
        method: tools/call
        name: echo
        argumentsSchema:
          type: object
          properties:
            message:
              type: string
          required:
            - message
        arguments:
          message: Hello
        responseSchema:
          type: object
          properties:
            content:
              type: array
              items:
                type: object
                properties:
                  type:
                    const: text
                  text:
                    type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          const: text
                        text:
                          type: string
              example:
                content:
                  - type: text
                    text: Hello
                isError: false
  /a2a:
    post:
      operationId: agent_message
      summary: agent message
      description: >-
        Official Powerduck example definition. Replace the example endpoint with your own service
        before sending.
      tags:
        - a2a
      x-protocol: a2a
      x-a2a:
        endpoint: 'http://127.0.0.1:9999/a2a'
        version: '1.0'
        binding: JSONRPC
        method: SendMessage
        requestSchema:
          type: object
          required:
            - message
          properties:
            message:
              type: object
              required:
                - messageId
                - role
                - parts
              properties:
                messageId:
                  type: string
                role:
                  type: string
                  enum:
                    - ROLE_USER
                    - ROLE_AGENT
                parts:
                  type: array
                  items:
                    type: object
                    properties:
                      text:
                        type: string
                    required:
                      - text
        responseSchema:
          type: object
          required:
            - jsonrpc
            - id
          properties:
            jsonrpc:
              const: '2.0'
            id:
              type: string
            result:
              type: object
              properties:
                message:
                  type: object
                  required:
                    - messageId
                    - role
                    - parts
                  properties:
                    messageId:
                      type: string
                    role:
                      type: string
                      enum:
                        - ROLE_USER
                        - ROLE_AGENT
                    parts:
                      type: array
                      items:
                        type: object
                        properties:
                          text:
                            type: string
                        required:
                          - text
                task:
                  type: object
            error:
              type: object
              required:
                - code
                - message
              properties:
                code:
                  type: integer
                message:
                  type: string
          oneOf:
            - required:
                - result
            - required:
                - error
        example:
          jsonrpc: '2.0'
          id: example-1
          method: SendMessage
          params:
            message:
              messageId: example-message
              role: ROLE_USER
              parts:
                - text: Hello
      responses:
        '200':
          description: 'JSON-RPC envelope: inspect result or error even on HTTP 200'
          content:
            application/json:
              schema:
                type: object
                required:
                  - jsonrpc
                  - id
                properties:
                  jsonrpc:
                    const: '2.0'
                  id:
                    type: string
                  result:
                    type: object
                    properties:
                      message:
                        type: object
                        required:
                          - messageId
                          - role
                          - parts
                        properties:
                          messageId:
                            type: string
                          role:
                            type: string
                            enum:
                              - ROLE_USER
                              - ROLE_AGENT
                          parts:
                            type: array
                            items:
                              type: object
                              properties:
                                text:
                                  type: string
                              required:
                                - text
                      task:
                        type: object
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
                oneOf:
                  - required:
                      - result
                  - required:
                      - error
              example:
                jsonrpc: '2.0'
                id: example-1
                result:
                  message:
                    messageId: reply-1
                    role: ROLE_AGENT
                    parts:
                      - text: Hello
components:
  schemas:
    Message:
      type: object
      required:
        - message
      properties:
        message:
          type: string
        id:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer