ISHOB Research Brief API

openapi: 3.2.0
info:
  title: ISHOB Research Brief API
  version: 1.0.0
  description: 'ISHOB is an x402-enabled utility gateway for autonomous agents: scheduled callbacks (agent alarms), token and wallet security checks, weather and location risk, document rendering, web extraction, company data and an open-licence research archive. Pay per call in USDC on Base; no account or API key.'
  contact:
    name: ISHOB
    email: contact@ishob.com
    url: https://ishob.com
  x-guidance: 'ISHOB is a gateway of tools for AI agents. Every operation with x-payment-info is paid per call with x402 (USDC on Base): call it, read the 402 PAYMENT-REQUIRED header, sign with an x402 client and retry. Invalid input is rejected with 400 before any payment is requested. The same tools are available over MCP at POST /mcp. Tool docs: https://ishob.com/tools'
servers:
- url: https://api.ishob.com
tags:
- name: Research Brief
paths:
  /v1/research-brief:
    post:
      operationId: research_brief
      summary: 'Research brief on any topic in one call: the best papers from ISHOB''s…'
      description: 'Research brief on any topic in one call: the best papers from ISHOB''s open-licence archive, filled with a live search of 250M+ scholarly works, each with authors, year, venue, DOI and citations; abstracts only for openly licensed papers (CC0 / public domain / CC BY / CC BY-SA), metadata and link for the rest; plus a short AI synthesis citing the papers as [n]. Checked before payment: if nothing is found anywhere the answer is a free 404 ''not_covered''.'
      x-payment:
        protocol: x402
        version: 2
        scheme: exact
        network: eip155:8453
        asset: USDC
        price_usd: '0.05'
      x-mcp-tool: research_brief
      responses:
        '200':
          description: Result (JSON); PAYMENT-RESPONSE header carries the settlement receipt
        '400':
          description: Invalid input (no payment requested)
        '402':
          description: 'Payment required: PAYMENT-REQUIRED header (base64 JSON) lists accepted payment requirements'
        '403':
          description: robots.txt disallows the target (no payment requested)
        '404':
          description: Not found (no payment requested)
        '503':
          description: Backend temporarily unavailable (no payment requested)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                  minLength: 3
                  maxLength: 200
                  description: Research question or topic
                max_papers:
                  type: integer
                  minimum: 1
                  maximum: 8
                  default: 5
                year_from:
                  type: integer
                  minimum: 1900
                  description: Only papers published in or after this year
                include_live:
                  type: boolean
                  default: true
                  description: Fill with live results from open scholarly sources when the archive has fewer papers
                synthesize:
                  type: boolean
                  default: true
                  description: Add the AI-written brief
            example:
              query: perovskite solar cell stability
              max_papers: 5
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.05'
        protocols:
        - x402: {}
      tags:
      - Research Brief