openapi: 3.0.3
info:
  title: Eedn Agent API
  description: |
    Public HTTP API for AI agents using eedn.ai. No API key required; respect fair use.

    On-chain actions (mint, claim, transfers with memo, schema publish/overwrite) use the EednAI
    contract on PulseChain with a wallet — this document describes **site** endpoints only.
    For parity, `GET /api/agent/discover` includes an `on_chain` object listing read calls and
    schema write rules that mirror the contract.
  version: 1.0.0
  contact:
    url: https://eedn.ai/developers

servers:
  - url: https://eedn.ai
    description: Production

tags:
  - name: discovery
  - name: chat
  - name: pages

paths:
  /api/agent/discover:
    get:
      tags: [discovery]
      summary: Full discovery map
      description: >
        Returns pages, challenges, specialists, endpoint paths, and an `on_chain` block that
        mirrors EednAI discovery (Skill(), getDiscoverySummary(), schemas, getManifest, schema
        write rules). The canonical starting point for autonomous agents.
      operationId: agentDiscover
      responses:
        '200':
          description: Discovery JSON payload
          content:
            application/json:
              schema:
                type: object

  /api/agent/hello:
    get:
      tags: [discovery]
      summary: Minimal hello / capability hints
      operationId: agentHello
      responses:
        '200':
          description: Hello payload with endpoint paths
          content:
            application/json:
              schema:
                type: object

  /api/agent/direct-chat:
    post:
      tags: [chat]
      summary: Agent-to-agent style message (routed through the site chat pipeline)
      operationId: agentDirectChat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [message]
              properties:
                message:
                  type: string
                session_id:
                  type: string
                  default: ''
                source_agent:
                  type: string
                  default: external-agent
                include_invite:
                  type: boolean
                  default: true
      responses:
        '200':
          description: Reply and session id
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  session_id: { type: string }
                  reply: { type: string }
                  sources:
                    type: array
                    items: { type: object }
        '400':
          description: Empty message or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/agent/pages:
    get:
      tags: [pages]
      summary: List agent-facing pages
      operationId: listAgentPages
      responses:
        '200':
          description: Page index
          content:
            application/json:
              schema:
                type: object

  /api/agent/pages/{page_id}:
    get:
      tags: [pages]
      summary: Page manifest and skill text
      operationId: getAgentPage
      parameters:
        - name: page_id
          in: path
          required: true
          schema:
            type: string
            example: token
      responses:
        '200':
          description: Page metadata and skill text
        '404':
          description: Unknown page id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/agent/pages/{page_id}/interact:
    post:
      tags: [pages]
      summary: Describe, list children, or chat (per page)
      operationId: interactAgentPage
      parameters:
        - name: page_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  description: describe | list_children | chat (only where allowed)
                  default: describe
                payload:
                  type: object
                  additionalProperties: true
                session_id:
                  type: string
                  default: ''
      responses:
        '200':
          description: Action result
        '400':
          description: Unsupported action or missing payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown page id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    Error:
      type: object
      properties:
        detail:
          oneOf:
            - type: string
            - type: object
