openapi: 3.1.0
info:
  title: Bindu Agent API
  description: |
    A2A Protocol compliant API for Bindu agents supporting JSON-RPC 2.0 methods for agent communication,
    task management, context management, DID resolution, and payment processing.
  version: 1.0.0
  contact:
    name: getbindu.com
    email: raahul@getbindu.com

servers:
  - url: http://localhost:3773
    description: Development server (default port)
  - url: https://hydra.getbindu.com
    description: OAuth2 authentication server

security:
  - BearerAuth: []

tags:
  - name: JSON-RPC
    description: JSON-RPC 2.0 endpoints for agent communication
  - name: Agent Discovery
    description: Agent metadata and capability discovery
  - name: DID Resolution
    description: Decentralized Identifier resolution
  - name: Skills
    description: Agent skills and capabilities
  - name: Negotiation
    description: Capability assessment endpoint for task negotiation
  - name: Payment
    description: x402 payment protocol endpoints
  - name: Health & Monitoring
    description: Health check and monitoring endpoints
  - name: Authentication
    description: OAuth2 authentication endpoints

paths:
  /oauth2/token:
    post:
      tags:
        - Authentication
      summary: OAuth2 Token Endpoint
      description: |
        Obtain an OAuth2 access token using client credentials grant.
        The client_id is the agent's DID and client_secret is obtained from oauth_credentials.json.
        
        **Credentials location:** `.bindu/oauth_credentials.json`
        
        **Grant type:** client_credentials
        
        **Scopes:**
        - openid: OpenID Connect scope
        - offline: Offline access
        - agent:read: Read agent data
        - agent:write: Write agent data
      operationId: getOAuth2Token
      servers:
        - url: https://hydra.getbindu.com
          description: OAuth2 authentication server
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
                - client_id
                - client_secret
                - scope
              properties:
                grant_type:
                  type: string
                  enum: [client_credentials]
                  description: OAuth2 grant type
                client_id:
                  type: string
                  description: Agent DID (from oauth_credentials.json)
                  example: "did:bindu:your_email_at_example_com:research_agent:9e84d316dd68482683ca3b3efc9c5500"
                client_secret:
                  type: string
                  description: Client secret (from oauth_credentials.json)
                  example: "45zleygc46gaAnLOkzMvsQ0Ui5D9fSH8FQQFCD0DwP8"
                scope:
                  type: string
                  description: Space-separated list of scopes
                  example: "openid offline agent:read agent:write"
      responses:
        '200':
          description: Access token granted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2TokenResponse'
              example:
                access_token: "ory_at_69tIcwQJXca4HQPWnLedJ2z0BjSztuK_HOhaDuMjF34.k4HCnESo7ja5-OxuUtW8z6iWBcdc9f4ofHa-hBaDlk4"
                expires_in: 3599
                scope: "openid offline agent:read agent:write"
                token_type: "bearer"
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /:
    post:
      tags:
        - JSON-RPC
      summary: JSON-RPC 2.0 Endpoint
      description: |
        Main JSON-RPC 2.0 endpoint supporting multiple methods:
        - message/send: Send messages to agent
        - message/stream: Stream messages from agent
        - tasks/get: Get task status
        - tasks/list: List all tasks
        - tasks/cancel: Cancel a task
        - tasks/feedback: Submit feedback for a task
        - contexts/list: List conversation contexts
        - contexts/clear: Clear a context
      operationId: jsonRpcEndpoint
      security:
        - BearerAuth: []
        - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/MessageSendRequest'
                - $ref: '#/components/schemas/TasksGetRequest'
                - $ref: '#/components/schemas/TasksListRequest'
                - $ref: '#/components/schemas/TasksCancelRequest'
                - $ref: '#/components/schemas/TasksFeedbackRequest'
                - $ref: '#/components/schemas/ContextsListRequest'
                - $ref: '#/components/schemas/ContextsClearRequest'
            examples:
              messageSend:
                summary: Send a message
                value:
                  jsonrpc: "2.0"
                  method: "message/send"
                  params:
                    message:
                      role: "user"
                      parts:
                        - kind: "text"
                          text: "provide sunset quote"
                      kind: "message"
                      messageId: "550e8400-e29b-41d4-a716-446655440038"
                      contextId: "550e8400-e29b-41d4-a716-446655440038"
                      taskId: "550e8400-e29b-41d4-a716-446655440078"
                    configuration:
                      acceptedOutputModes:
                        - "application/json"
                  id: "550e8400-e29b-41d4-a716-446655440024"

              messageSendWithPayment:
                summary: Send a message with x402 payment
                value:
                  jsonrpc: "2.0"
                  method: "message/send"
                  params:
                    message:
                      role: "user"
                      parts:
                        - kind: "text"
                          text: "provide sunset quote"
                      kind: "message"
                      messageId: "550e8400-e29b-41d4-a716-446655440039"
                      contextId: "550e8400-e29b-41d4-a716-446655440038"
                      taskId: "550e8400-e29b-41d4-a716-446655440078"
                      metadata:
                        x402.payment.status: "payment-submitted"
                        x402.payment.payload:
                          resource: "/agent/first Agent"
                          scheme: "exact"
                          network: "base-sepolia"
                          asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
                          payTo: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
                          amount: "10000000000"
                          signature: "0x<YOUR_WALLET_SIGNATURE_HERE>"
                          timestamp: "2025-10-26T14:47:52.183416+00:00"
                          payer: "0x<YOUR_WALLET_ADDRESS>"
                    configuration:
                      acceptedOutputModes:
                        - "application/json"
                  id: "550e8400-e29b-41d4-a716-446655440025"

              messageSendWithReference:
                summary: Send a message with reference to previous task
                value:
                  jsonrpc: "2.0"
                  method: "message/send"
                  params:
                    message:
                      role: "user"
                      parts:
                        - kind: "text"
                          text: "make it shorter"
                      kind: "message"
                      messageId: "550e8400-e29b-41d4-a716-446655440027"
                      contextId: "550e8400-e29b-41d4-a716-446655440027"
                      taskId: "550e8400-e29b-41d4-a716-446655440042"
                      referenceTaskIds:
                        - "550e8400-e29b-41d4-a716-446655440041"
                    configuration:
                      acceptedOutputModes:
                        - "application/json"
                  id: "550e8400-e29b-41d4-a716-446655440024"

              tasksGet:
                summary: Get task status
                value:
                  jsonrpc: "2.0"
                  method: "tasks/get"
                  params:
                    taskId: "550e8400-e29b-41d4-a716-446655440013"
                  id: "550e8400-e29b-41d4-a716-446655440014"

              tasksList:
                summary: List all tasks
                value:
                  jsonrpc: "2.0"
                  method: "tasks/list"
                  params: {}
                  id: "550e8400-e29b-41d4-a716-446655440099"

              tasksCancel:
                summary: Cancel a task
                value:
                  jsonrpc: "2.0"
                  method: "tasks/cancel"
                  params:
                    taskId: "550e8400-e29b-41d4-a716-446655440042"
                  id: "550e8400-e29b-41d4-a716-446655440042"

              tasksFeedback:
                summary: Submit task feedback
                value:
                  jsonrpc: "2.0"
                  method: "tasks/feedback"
                  params:
                    taskId: "550e8400-e29b-41d4-a716-446655440045"
                    feedback: "Great job! The response was very helpful and accurate."
                    rating: 5
                    metadata:
                      category: "quality"
                      source: "user"
                      helpful: true
                  id: "550e8400-e29b-41d4-a716-446655440024"

              contextsList:
                summary: List contexts
                value:
                  jsonrpc: "2.0"
                  method: "contexts/list"
                  params:
                    length: 10
                  id: "550e8400-e29b-41d4-a716-446655440025"

              contextsClear:
                summary: Clear a context
                value:
                  jsonrpc: "2.0"
                  method: "contexts/clear"
                  params:
                    contextId: "550e8400-e29b-41d4-a716-446655440037"
                  id: "550e8400-e29b-41d4-a716-446655440025"
      responses:
        '200':
          description: Successful JSON-RPC response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/JsonRpcSuccessResponse'
                  - $ref: '#/components/schemas/JsonRpcErrorResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    jsonrpc: "2.0"
                    result:
                      task:
                        taskId: "550e8400-e29b-41d4-a716-446655440078"
                        contextId: "550e8400-e29b-41d4-a716-446655440038"
                        status:
                          state: "completed"
                          timestamp: "2025-10-26T14:47:52.183416+00:00"
                        artifacts:
                          - kind: "text"
                            text: "The sunset paints the sky with hope for tomorrow."
                    id: "550e8400-e29b-41d4-a716-446655440024"

                taskCancelSuccess:
                  summary: Task canceled successfully
                  value:
                    jsonrpc: "2.0"
                    result:
                      task:
                        taskId: "550e8400-e29b-41d4-a716-446655440042"
                        contextId: "550e8400-e29b-41d4-a716-446655440038"
                        status:
                          state: "canceled"
                          timestamp: "2025-10-26T14:47:52.183416+00:00"
                        history:
                          - role: "user"
                            parts:
                              - kind: "text"
                                text: "Generate a long report"
                            kind: "message"
                            messageId: "550e8400-e29b-41d4-a716-446655440040"
                            contextId: "550e8400-e29b-41d4-a716-446655440038"
                            taskId: "550e8400-e29b-41d4-a716-446655440042"
                        metadata: {}
                    id: "550e8400-e29b-41d4-a716-446655440042"

                error:
                  summary: Error response
                  value:
                    jsonrpc: "2.0"
                    error:
                      code: -32602
                      message: "Invalid params"
                      data:
                        details: "Missing required field: taskId"
                    id: "550e8400-e29b-41d4-a716-446655440024"

                taskNotCancelable:
                  summary: Cannot cancel completed task
                  value:
                    jsonrpc: "2.0"
                    error:
                      code: -32002
                      message: "Task cannot be canceled in 'completed' state. Tasks can only be canceled while pending or running."
                    id: "550e8400-e29b-41d4-a716-446655440042"

                taskNotFound:
                  summary: Task not found
                  value:
                    jsonrpc: "2.0"
                    error:
                      code: -32001
                      message: "The specified task ID was not found. The task may have been completed, canceled, or expired. Check task status: GET /tasks/{id}"
                    id: "550e8400-e29b-41d4-a716-446655440042"

  /.well-known/agent.json:
    get:
      tags:
        - Agent Discovery
      summary: Get Agent Card
      description: |
        Returns the agent's metadata card following the A2A Protocol specification.
        Includes agent capabilities, supported features, and discovery information.
      operationId: getAgentCard
      security: []
      responses:
        '200':
          description: Agent card metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCard'
              example:
                id: "aa8bf76b-1d19-47a4-9316-7220ce8dd7a0"
                name: "research_agent"
                description: "A research assistant agent"
                url: "http://localhost"
                version: "2026.6.7.dev65+g6742cd6eb.d20260210"
                protocolVersion: "1.0.0"
                skills:
                  - id: "question-answering-v1"
                    name: "question-answering"
                    documentationPath: "http://localhost/agent/skills/question-answering-v1"
                  - id: "pdf-processing-v1"
                    name: "pdf-processing"
                    documentationPath: "http://localhost/agent/skills/pdf-processing-v1"
                capabilities:
                  extensions:
                    - uri: "did:bindu:your_email_at_example_com:research_agent:aa8bf76b1d1947a493167220ce8dd7a0"
                      description: "DID-based identity for research_agent"
                      required: false
                      params:
                        author: "your.email@example.com"
                        agent_name: "research_agent"
                        agent_id: "aa8bf76b1d1947a493167220ce8dd7a0"
                  pushNotifications: false
                  streaming: false
                kind: "agent"
                numHistorySessions: 10
                extraData:
                  created: 1770833216
                  server_info: "bindu Agent Server"
                debugMode: false
                debugLevel: 1
                monitoring: false
                telemetry: true
                agentTrust:
                  identityProvider: "custom"
                  inheritedRoles: []
                  creatorId: "system"
                  creationTimestamp: 1770821399
                  trustVerificationRequired: false
                  allowedOperations: {}
                defaultInputModes:
                  - "text/plain"
                  - "application/json"
                defaultOutputModes:
                  - "text/plain"
                  - "application/json"

  /did/resolve:

    post:
      tags:
        - DID Resolution
      summary: Resolve DID
      description: |
        Resolves a Decentralized Identifier (DID) to its W3C-compliant DID document.
        Supports custom Bindu DID format: did:bindu:{author}:{agent_name}:{agent_id}
      operationId: resolveDid
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - did
              properties:
                did:
                  type: string
                  description: The DID to resolve
                  example: "did:bindu:gaurikasethi88_at_gmail_com:echo_agent:352c17d030fb4bf1ab33d04b102aef3d"
      responses:
        '200':
          description: DID document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DidDocument'
              example:
                "@context":
                  - "https://www.w3.org/ns/did/v1"
                  - "https://getbindu.com/ns/v1"
                id: "did:bindu:your_email_at_example_com:research_agent:aa8bf76b1d1947a493167220ce8dd7a0"
                created: "2026-02-11T14:49:59.808057+00:00"
                authentication:
                  - id: "did:bindu:your_email_at_example_com:research_agent:aa8bf76b1d1947a493167220ce8dd7a0#key-1"
                    type: "Ed25519VerificationKey2020"
                    controller: "did:bindu:your_email_at_example_com:research_agent:aa8bf76b1d1947a493167220ce8dd7a0"
                    publicKeyBase58: "42ob7CWrucLUpyCLjafmtHEYVTrJTJmKqkLCuMohKn6y"
        '400':
          description: Invalid DID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: DID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
              example:
                jsonrpc: "2.0"
                error:
                  code: -32603
                  message: "An internal server error occurred while processing the request. Please try again or contact support if the issue persists. See: /health"
                  data: "DID 'did:bindu:gaurikasethi88_at_gmail_com:echo_agent:352c17d030fb4bf1ab33d04b102aef3d' not found"
                id: null

  /agent/negotiation:
    post:
      tags:
        - Negotiation
      summary: Assess Task Capability
      description: |
        Assess agent's capability to handle a task. Evaluates skill match, IO compatibility,
        performance, load, and cost to produce an acceptance decision with confidence and detailed scoring.

        **Required fields:**
        - task_summary (string, max 10000 chars)

        **Optional fields:**
        - task_details, input_mime_types, output_mime_types, max_latency_ms, max_cost_amount,
          required_tools, forbidden_tools, min_score, weights
      operationId: assessTaskCapability
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NegotiationRequest'
            example:
              task_summary: "Extract tables and text from PDF invoices and text"
              task_details: "Need to process multiple invoice PDFs and extract structured data including line items, totals, and vendor information"
              input_mime_types:
                - "application/pdf"
              output_mime_types:
                - "application/json"
              max_latency_ms: 5000
              max_cost_amount: "0.001"
              required_tools: []
              forbidden_tools: []
              min_score: 0.7
              weights:
                skill_match: 0.6
                io_compatibility: 0.2
                performance: 0.1
                load: 0.05
                cost: 0.05
      responses:
        '200':
          description: Capability assessment result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NegotiationResponse'
              example:
                accepted: false
                score: 0.3686
                confidence: 0.9
                rejection_reason: "score_below_threshold"
                skill_matches:
                  - skill_id: "pdf-processing-v1"
                    skill_name: "pdf-processing"
                    score: 0.1143
                    reasons:
                      - "tags: pdf, tables"
                      - "capabilities: text_extraction"
                matched_tags:
                  - "tables"
                  - "pdf"
                matched_capabilities:
                  - "text_extraction"
                latency_estimate_ms: 2000
                queue_depth: 0
                subscores:
                  skill_match: 0.1143
                  io_compatibility: 1.0
                  load: 1.0
                  cost: 1.0
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /agent/skills:
    get:
      tags:
        - Skills
      summary: List Agent Skills
      description: Returns a list of all skills supported by the agent
      operationId: listSkills
      security: []
      responses:
        '200':
          description: List of skills
          content:
            application/json:
              schema:
                type: object
                properties:
                  skills:
                    type: array
                    items:
                      $ref: '#/components/schemas/SkillSummary'
                  total:
                    type: integer
                    description: Total number of skills
              example:
                skills:
                  - id: "question-answering-v1"
                    name: "question-answering"
                    description: "Provides intelligent question answering capabilities for general knowledge queries.\nUse when users ask factual questions, need explanations, or require information retrieval.\n"
                    version: "1.0.0"
                    tags:
                      - "qa"
                      - "knowledge"
                      - "reasoning"
                      - "general"
                    input_modes:
                      - "text/plain"
                      - "application/json"
                    output_modes:
                      - "text/plain"
                      - "application/json"
                    examples:
                      - "What is photosynthesis?"
                      - "How does a refrigerator work?"
                      - "Why do we see different phases of the moon?"
                    documentation_path: "beginner/skills/question-answering/skill.yaml"
                  - id: "pdf-processing-v1"
                    name: "pdf-processing"
                    description: "Extract text, fill forms, and extract tables from PDF documents.\nHandles both standard text-based PDFs and scanned documents with OCR.\n"
                    version: "1.0.0"
                    tags:
                      - "pdf"
                      - "documents"
                      - "extraction"
                      - "forms"
                      - "tables"
                    input_modes:
                      - "application/pdf"
                    output_modes:
                      - "text/plain"
                      - "application/json"
                      - "application/pdf"
                    examples:
                      - "Extract text from this PDF document"
                      - "Fill out this PDF form with the provided data"
                      - "Extract tables from this invoice PDF"
                    documentation_path: "beginner/skills/pdf-processing/skill.yaml"
                total: 2

  /agent/skills/{skillId}:
    get:
      tags:
        - Skills
      summary: Get Skill Details
      description: Returns detailed information about a specific skill
      operationId: getSkillDetails
      security: []
      parameters:
        - name: skillId
          in: path
          required: true
          description: The skill identifier
          schema:
            type: string
          example: "question-answering-v1"
      responses:
        '200':
          description: Skill details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillDetails'
              example:
                id: "pdf-processing-v1"
                name: "pdf-processing"
                description: "Extract text, fill forms, and extract tables from PDF documents.\nHandles both standard text-based PDFs and scanned documents with OCR.\n"
                tags:
                  - "pdf"
                  - "documents"
                  - "extraction"
                  - "forms"
                  - "tables"
                input_modes:
                  - "application/pdf"
                output_modes:
                  - "text/plain"
                  - "application/json"
                  - "application/pdf"
                version: "1.0.0"
                author: "raahul@getbindu.com"
                examples:
                  - "Extract text from this PDF document"
                  - "Fill out this PDF form with the provided data"
                  - "Extract tables from this invoice PDF"
                capabilities_detail:
                  text_extraction:
                    supported: true
                    types: ["standard", "scanned_with_ocr"]
                    languages: ["eng", "spa", "fra", "deu"]
                  form_filling:
                    supported: true
                    field_types: ["text", "checkbox", "dropdown", "radio"]
                  table_extraction:
                    supported: true
                    output_formats: ["json", "csv", "dataframe"]
                requirements:
                  packages:
                    - "pypdf>=3.0.0"
                    - "pdfplumber>=0.9.0"
                  system:
                    - "tesseract-ocr"
                  min_memory_mb: 512
                performance:
                  avg_processing_time_ms: 2000
                  max_file_size_mb: 50
                  max_pages: 500
                  concurrent_requests: 5
                allowed_tools:
                  - "Read"
                  - "Write"
                  - "Execute"
                documentation:
                  overview: "This agent specializes in PDF document processing..."
                  use_cases:
                    when_to_use:
                      - "User uploads a PDF and asks to extract text"
                      - "User needs to fill out PDF forms programmatically"
                    when_not_to_use:
                      - "PDF editing or modification"
                      - "PDF creation from scratch"
                  best_practices:
                    for_developers:
                      - "Check file size before processing (max 50MB)"
                      - "Use OCR only when necessary"
                    for_orchestrators:
                      - "Route PDF operations based on operation type"
                      - "Consider file size for performance estimation"
                assessment:
                  keywords:
                    - "pdf"
                    - "extract"
                    - "document"
                    - "form"
                    - "table"
                  specializations:
                    - domain: "invoice_processing"
                      confidence_boost: 0.3
                  anti_patterns:
                    - "pdf editing"
                    - "pdf creation"
                documentation_path: "beginner/skills/pdf-processing/skill.yaml"
                has_documentation: true
        '404':
          description: Skill not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /agent/skills/{skillId}/documentation:
    get:
      tags:
        - Skills
      summary: Get Skill Documentation
      description: Returns human-readable documentation for a specific skill
      operationId: getSkillDocumentation
      security: []
      parameters:
        - name: skillId
          in: path
          required: true
          description: The skill identifier
          schema:
            type: string
          example: "question-answering-v1"
      responses:
        '200':
          description: Skill documentation
          content:
            text/markdown:
              schema:
                type: string
              example: |
                # Question Answering Skill

                This skill allows the agent to answer questions based on provided context.

                ## Usage

                Send a message with your question and the agent will respond with an answer.

                ## Examples

                - "What is the capital of France?"
                - "Explain quantum computing"
        '404':
          description: Skill not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/start-payment-session:
    post:
      tags:
        - Payment
      summary: Start Payment Session
      description: |
        Initiates a payment session for x402 protocol.
        Returns payment requirements and session information.
      operationId: startPaymentSession
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Payment session started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentSession'
              example:
                sessionId: "Z_1Y3U3waXK2YUKB6llcIwn9XJcviEBhuFL8WUutAQ8"  # pragma: allowlist secret
                paymentRequirements:
                  resource: "/agent/first Agent"
                  scheme: "exact"
                  network: "base-sepolia"
                  asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
                  payTo: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
                  amount: "10000000000"
                  description: "Payment for agent service"
                expiresAt: "2025-10-26T15:47:52.183416+00:00"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/payment-status/{sessionId}:
    get:
      tags:
        - Payment
      summary: Get Payment Status
      description: |
        Retrieves the status of a payment session.
        Used to verify payment completion.
      operationId: getPaymentStatus
      security:
        - BearerAuth: []
      parameters:
        - name: sessionId
          in: path
          required: true
          description: The payment session identifier
          schema:
            type: string
          example: "Z_1Y3U3waXK2YUKB6llcIwn9XJcviEBhuFL8WUutAQ8"
      responses:
        '200':
          description: Payment status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentStatus'
              example:
                sessionId: "Z_1Y3U3waXK2YUKB6llcIwn9XJcviEBhuFL8WUutAQ8"
                status: "completed"
                transactionHash: "0x..."
                timestamp: "2025-10-26T14:47:52.183416+00:00"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /payment-capture:
    get:
      tags:
        - Payment
      summary: Payment Capture Page
      description: |
        Browser page to capture payment. Shows paywall UI and captures payment token when completed.
        This is typically opened in a browser, not called programmatically.
      operationId: paymentCapturePage
      security: []
      parameters:
        - name: session_id
          in: query
          required: true
          description: The payment session ID
          schema:
            type: string
          example: "Z_1Y3U3waXK2YUKB6llcIwn9XJcviEBhuFL8WUutAQ8"
      responses:
        '200':
          description: Payment capture page HTML
          content:
            text/html:
              schema:
                type: string
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /health:
    get:
      tags:
        - Health & Monitoring
      summary: Health Check
      description: |
        Health check endpoint for service monitoring. Returns service status, uptime,
        version information, and readiness state.
      operationId: healthCheck
      security: []
      responses:
        '200':
          description: Service health status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              example:
                status: "ok"
                uptime_seconds: 12036.61
                version: "2026.6.7.dev65+g6742cd6eb.d20260210"
                ready: true

  /metrics:
    get:
      tags:
        - Health & Monitoring
      summary: Prometheus Metrics
      description: |
        Prometheus metrics endpoint for scraping. Returns metrics in Prometheus text format.

        **Metrics exposed:**
        - http_requests_total: Total HTTP requests by method, endpoint, and status
        - http_request_duration_seconds: HTTP request latency histogram
        - agent_tasks_active: Currently active tasks per agent
        - http_request_size_bytes: HTTP request body size summary
        - http_response_size_bytes: HTTP response body size summary
        - http_requests_in_flight: Current number of HTTP requests being processed
      operationId: prometheusMetrics
      security: []
      responses:
        '200':
          description: Prometheus metrics in text format
          content:
            text/plain:
              schema:
                type: string
              example: |
                # HELP http_requests_total Total number of HTTP requests
                # TYPE http_requests_total counter
                http_requests_total{method="GET",endpoint="/.well-known/agent.json",status="200"} 1
                http_requests_total{method="POST",endpoint="/",status="200"} 6
                http_requests_total{method="POST",endpoint="/agent/negotiation",status="200"} 2
                
                # HELP http_request_duration_seconds HTTP request latency
                # TYPE http_request_duration_seconds histogram
                http_request_duration_seconds_bucket{le="0.1"} 1
                http_request_duration_seconds_bucket{le="0.5"} 1
                http_request_duration_seconds_bucket{le="1.0"} 1
                http_request_duration_seconds_bucket{le="+Inf"} 9
                http_request_duration_seconds_sum 20.4
                http_request_duration_seconds_count 9
                
                # HELP agent_tasks_active Currently active tasks
                # TYPE agent_tasks_active gauge
                agent_tasks_active{agent_id="did:bindu:your_email_at_example_com:research_agent:aa8bf76b1d1947a493167220ce8dd7a0"} 0
                
                # HELP http_request_size_bytes HTTP request body size
                # TYPE http_request_size_bytes summary
                http_request_size_bytes_sum 1868
                http_request_size_bytes_count 8
                
                # HELP http_response_size_bytes HTTP response body size
                # TYPE http_response_size_bytes summary
                http_response_size_bytes_sum 2637
                http_response_size_bytes_count 9
                
                # HELP http_requests_in_flight Current number of HTTP requests being processed
                # TYPE http_requests_in_flight gauge
                http_requests_in_flight 0

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: JWT token for authentication

  schemas:
    # JSON-RPC Request Schemas
    MessageSendRequest:
      type: object
      required:
        - jsonrpc
        - method
        - params
        - id
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
        method:
          type: string
          enum: ["message/send"]
        params:
          type: object
          required:
            - message
          properties:
            message:
              $ref: '#/components/schemas/Message'
            configuration:
              $ref: '#/components/schemas/Configuration'
        id:
          type: string
          description: Request identifier

    TasksGetRequest:
      type: object
      required:
        - jsonrpc
        - method
        - params
        - id
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
        method:
          type: string
          enum: ["tasks/get"]
        params:
          type: object
          required:
            - taskId
          properties:
            taskId:
              type: string
              format: uuid
        id:
          type: string

    TasksListRequest:
      type: object
      required:
        - jsonrpc
        - method
        - params
        - id
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
        method:
          type: string
          enum: ["tasks/list"]
        params:
          type: object
          properties:
            limit:
              type: integer
              minimum: 1
              maximum: 100
            offset:
              type: integer
              minimum: 0
        id:
          type: string

    TasksCancelRequest:
      type: object
      required:
        - jsonrpc
        - method
        - params
        - id
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
        method:
          type: string
          enum: ["tasks/cancel"]
        params:
          type: object
          required:
            - taskId
          properties:
            taskId:
              type: string
              format: uuid
        id:
          type: string

    TasksFeedbackRequest:
      type: object
      required:
        - jsonrpc
        - method
        - params
        - id
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
        method:
          type: string
          enum: ["tasks/feedback"]
        params:
          type: object
          required:
            - taskId
            - feedback
          properties:
            taskId:
              type: string
              format: uuid
            feedback:
              type: string
            rating:
              type: integer
              minimum: 1
              maximum: 5
            metadata:
              type: object
              additionalProperties: true
        id:
          type: string

    ContextsListRequest:
      type: object
      required:
        - jsonrpc
        - method
        - params
        - id
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
        method:
          type: string
          enum: ["contexts/list"]
        params:
          type: object
          properties:
            length:
              type: integer
              minimum: 1
              maximum: 100
        id:
          type: string

    ContextsClearRequest:
      type: object
      required:
        - jsonrpc
        - method
        - params
        - id
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
        method:
          type: string
          enum: ["contexts/clear"]
        params:
          type: object
          required:
            - contextId
          properties:
            contextId:
              type: string
              format: uuid
        id:
          type: string

    # JSON-RPC Response Schemas
    JsonRpcSuccessResponse:
      type: object
      required:
        - jsonrpc
        - result
        - id
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
        result:
          type: object
          description: Method-specific result
        id:
          type: string

    JsonRpcErrorResponse:
      type: object
      required:
        - jsonrpc
        - error
        - id
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: integer
              description: JSON-RPC error code
            message:
              type: string
              description: Error message
            data:
              type: object
              description: Additional error data
        id:
          type: string

    # Core Domain Schemas
    Message:
      type: object
      required:
        - role
        - parts
        - kind
        - messageId
        - contextId
        - taskId
      properties:
        role:
          type: string
          enum: ["user", "agent"]
        parts:
          type: array
          items:
            $ref: '#/components/schemas/MessagePart'
        kind:
          type: string
          enum: ["message"]
        messageId:
          type: string
          format: uuid
        contextId:
          type: string
          format: uuid
        taskId:
          type: string
          format: uuid
        referenceTaskIds:
          type: array
          items:
            type: string
            format: uuid
          description: References to previous tasks in the conversation
        metadata:
          type: object
          additionalProperties: true
          description: Additional metadata (e.g., payment information)

    MessagePart:
      type: object
      required:
        - kind
      properties:
        kind:
          type: string
          enum: ["text", "file", "data"]
        text:
          type: string
          description: Text content (for kind=text)
        file:
          type: object
          description: File reference (for kind=file)
        data:
          type: object
          description: Structured data (for kind=data)

    Configuration:
      type: object
      properties:
        acceptedOutputModes:
          type: array
          items:
            type: string
          description: Accepted MIME types for output
          example: ["application/json", "text/plain"]

    Task:
      type: object
      required:
        - taskId
        - contextId
        - status
        - kind
      properties:
        taskId:
          type: string
          format: uuid
        contextId:
          type: string
          format: uuid
        kind:
          type: string
          enum: ["task"]
        status:
          $ref: '#/components/schemas/TaskStatus'
        artifacts:
          type: array
          items:
            $ref: '#/components/schemas/Artifact'
        history:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        metadata:
          type: object
          additionalProperties: true

    TaskStatus:
      type: object
      required:
        - state
        - timestamp
      properties:
        state:
          type: string
          enum:
            - submitted
            - working
            - input-required
            - auth-required
            - completed
            - canceled
            - failed
        timestamp:
          type: string
          format: date-time

    Artifact:
      type: object
      required:
        - kind
      properties:
        kind:
          type: string
          enum: ["text", "file", "data"]
        text:
          type: string
        file:
          type: object
        data:
          type: object

    AgentCard:
      type: object
      required:
        - id
        - name
        - version
        - protocolVersion
        - kind
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the agent
        name:
          type: string
          description: Agent name
        description:
          type: string
          description: Agent description
        url:
          type: string
          description: Base URL for the agent
        version:
          type: string
          description: Agent version
        protocolVersion:
          type: string
          description: A2A protocol version
        skills:
          type: array
          items:
            type: object
            required:
              - id
              - name
            properties:
              id:
                type: string
              name:
                type: string
              documentationPath:
                type: string
        capabilities:
          type: object
          properties:
            extensions:
              type: array
              items:
                type: object
                properties:
                  uri:
                    type: string
                  description:
                    type: string
                  required:
                    type: boolean
                  params:
                    type: object
            pushNotifications:
              type: boolean
            streaming:
              type: boolean
        kind:
          type: string
          description: Resource kind (e.g., "agent")
        numHistorySessions:
          type: integer
          description: Number of history sessions to maintain
        extraData:
          type: object
          description: Additional metadata
        debugMode:
          type: boolean
          description: Whether debug mode is enabled
        debugLevel:
          type: integer
          description: Debug level (0-3)
        monitoring:
          type: boolean
          description: Whether monitoring is enabled
        telemetry:
          type: boolean
          description: Whether telemetry is enabled
        agentTrust:
          type: object
          description: Trust and identity information
          properties:
            identityProvider:
              type: string
            inheritedRoles:
              type: array
              items:
                type: string
            creatorId:
              type: string
            creationTimestamp:
              type: integer
            trustVerificationRequired:
              type: boolean
            allowedOperations:
              type: object
        defaultInputModes:
          type: array
          items:
            type: string
          description: Default accepted input MIME types
        defaultOutputModes:
          type: array
          items:
            type: string
          description: Default output MIME types

    DidDocument:
      type: object
      required:
        - "@context"
        - id
      properties:
        "@context":
          type: array
          items:
            type: string
        id:
          type: string
          description: The DID
        created:
          type: string
          format: date-time
        authentication:
          type: array
          items:
            type: object
        bindu:
          type: object
          description: Bindu-specific metadata
        service:
          type: array
          items:
            type: object

    SkillSummary:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: Unique skill identifier
        name:
          type: string
          description: Skill name
        description:
          type: string
          description: Skill description
        version:
          type: string
          description: Skill version
        tags:
          type: array
          items:
            type: string
          description: Skill tags for categorization
        input_modes:
          type: array
          items:
            type: string
          description: Accepted input MIME types
        output_modes:
          type: array
          items:
            type: string
          description: Supported output MIME types
        examples:
          type: array
          items:
            type: string
          description: Example use cases
        documentation_path:
          type: string
          description: Path to skill documentation file

    SkillDetails:
      type: object
      required:
        - id
        - name
        - version
      properties:
        id:
          type: string
          description: Unique skill identifier
        name:
          type: string
          description: Skill name
        description:
          type: string
          description: Detailed skill description
        tags:
          type: array
          items:
            type: string
          description: Skill tags for categorization
        input_modes:
          type: array
          items:
            type: string
          description: Accepted input MIME types
        output_modes:
          type: array
          items:
            type: string
          description: Supported output MIME types
        version:
          type: string
          description: Skill version
        author:
          type: string
          description: Skill author email
        examples:
          type: array
          items:
            type: string
          description: Example use cases
        capabilities_detail:
          type: object
          description: Detailed capability information
        requirements:
          type: object
          description: Package and system requirements
          properties:
            packages:
              type: array
              items:
                type: string
            system:
              type: array
              items:
                type: string
            min_memory_mb:
              type: integer
        performance:
          type: object
          description: Performance metrics and constraints
          properties:
            avg_processing_time_ms:
              type: integer
            max_file_size_mb:
              type: integer
            max_pages:
              type: integer
            concurrent_requests:
              type: integer
        allowed_tools:
          type: array
          items:
            type: string
          description: Allowed tool operations
        documentation:
          type: object
          description: Comprehensive documentation
          properties:
            overview:
              type: string
            use_cases:
              type: object
            input_structure:
              type: string
            output_format:
              type: string
            error_handling:
              type: array
              items:
                type: string
            examples:
              type: array
              items:
                type: object
            best_practices:
              type: object
        assessment:
          type: object
          description: Assessment and routing information
          properties:
            keywords:
              type: array
              items:
                type: string
            specializations:
              type: array
              items:
                type: object
            anti_patterns:
              type: array
              items:
                type: string
        documentation_path:
          type: string
          description: Path to skill documentation file
        has_documentation:
          type: boolean
          description: Whether documentation is available

    PaymentSession:
      type: object
      required:
        - sessionId
        - paymentRequirements
      properties:
        sessionId:
          type: string
        paymentRequirements:
          $ref: '#/components/schemas/PaymentRequirements'
        expiresAt:
          type: string
          format: date-time

    PaymentRequirements:
      type: object
      required:
        - resource
        - scheme
        - network
        - asset
        - payTo
        - amount
      properties:
        resource:
          type: string
          description: Resource being paid for
        scheme:
          type: string
          enum: ["exact", "range"]
        network:
          type: string
          description: Blockchain network
          example: "base-sepolia"
        asset:
          type: string
          description: Token contract address
        payTo:
          type: string
          description: Recipient address
        amount:
          type: string
          description: Amount in atomic units
        description:
          type: string

    PaymentStatus:
      type: object
      required:
        - sessionId
        - status
      properties:
        sessionId:
          type: string
        status:
          type: string
          enum: ["pending", "completed", "failed", "expired"]
        transactionHash:
          type: string
        timestamp:
          type: string
          format: date-time

    NegotiationRequest:
      type: object
      required:
        - task_summary
      properties:
        task_summary:
          type: string
          maxLength: 10000
          description: Brief summary of the task
        task_details:
          type: string
          description: Detailed task description
        input_mime_types:
          type: array
          items:
            type: string
          description: Accepted input MIME types
        output_mime_types:
          type: array
          items:
            type: string
          description: Accepted output MIME types
        max_latency_ms:
          type: integer
          description: Maximum acceptable latency in milliseconds
        max_cost_amount:
          type: string
          description: Maximum acceptable cost as a string
        required_tools:
          type: array
          items:
            type: string
          description: Tools that must be available
        forbidden_tools:
          type: array
          items:
            type: string
          description: Tools that must not be used
        min_score:
          type: number
          minimum: 0
          maximum: 1
          description: Minimum acceptance score threshold
        weights:
          type: object
          description: Scoring weights for different factors
          properties:
            skill_match:
              type: number
            io_compatibility:
              type: number
            performance:
              type: number
            load:
              type: number
            cost:
              type: number

    NegotiationResponse:
      type: object
      required:
        - accepted
        - score
        - confidence
      properties:
        accepted:
          type: boolean
          description: Whether the agent accepts the task
        score:
          type: number
          minimum: 0
          maximum: 1
          description: Overall weighted score
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: Confidence in the assessment
        rejection_reason:
          type: string
          description: Reason for rejection if not accepted
        skill_matches:
          type: array
          description: Matched skills with scores
          items:
            type: object
            properties:
              skill_id:
                type: string
              skill_name:
                type: string
              score:
                type: number
              reasons:
                type: array
                items:
                  type: string
        matched_tags:
          type: array
          items:
            type: string
          description: Tags that matched the task
        matched_capabilities:
          type: array
          items:
            type: string
          description: Capabilities that matched the task
        latency_estimate_ms:
          type: integer
          description: Estimated latency in milliseconds
        queue_depth:
          type: integer
          description: Current queue depth
        subscores:
          type: object
          description: Individual scoring factors
          properties:
            skill_match:
              type: number
            io_compatibility:
              type: number
            performance:
              type: number
            load:
              type: number
            cost:
              type: number

    HealthResponse:
      type: object
      required:
        - status
        - ready
      properties:
        status:
          type: string
          description: Overall service health status
          example: "ok"
        uptime_seconds:
          type: number
          description: Service uptime in seconds (float)
          example: 12036.61
        version:
          type: string
          description: Service version
        ready:
          type: boolean
          description: Whether service is ready to accept requests

    OAuth2TokenResponse:
      type: object
      required:
        - access_token
        - token_type
        - expires_in
      properties:
        access_token:
          type: string
          description: The OAuth2 access token (JWT)
        token_type:
          type: string
          description: Token type (always "bearer")
          example: "bearer"
        expires_in:
          type: integer
          description: Token expiration time in seconds
          example: 3599
        scope:
          type: string
          description: Space-separated list of granted scopes
          example: "openid offline agent:read agent:write"

    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        details:
          type: string