Swarmio Search API

openapi: 3.2.0
info:
  title: SwarmIO Cloud Search API
  version: 1.0.0
  description: 'The x402-payable and public agent surface of ioswarm.io — this root document is what agent discovery (x402scan register-origin, the agentcash probe) reads. The full contract, including the credit-billed account API (sk_swarm_ key), is at /api/v1/openapi.json; the human/agent doc is /llms.txt.


    AI that does real work for you. One POST kicks off a job that searches the web, reads sources, and writes a cited report; poll for the result.


    Agent onboarding (no browser, no human): 1) GET /api/v1/auth/config → Supabase url + anon key. 2) POST {supabase_url}/auth/v1/signup → access_token (email confirmation off). 3) POST /api/v1/agent/register → agent id. 4) POST /api/v1/account/api-keys → sk_swarm_ key (shown once). 5) Authorization: Bearer sk_swarm_… on everything else. Starter credits land automatically on the first authenticated call.


    The full agent doc is https://ioswarm.io/llms.txt; the A2A agent card is at /.well-known/agent-card.json; an MCP facade is at /mcp.'
  x-guidance: 'Agent surface. Paid x402 primitives answer a bare call with a 402 carrying the payment requirements (v1 in the body, v2 base64 in the PAYMENT-REQUIRED header): sign the EIP-3009 transferWithAuthorization they describe and re-send the identical request with X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2). Paid per call: /api/v1/search ($0.02, 25 free/day), /api/v1/search/report ($0.05), /api/v1/news/brief ($0.05), /api/v1/market/price ($0.02, 10 free/day), /api/v1/video/transcript ($0.02, 10 free/day), /api/v1/video/search ($0.02, 25 free/day), /api/v1/x402/quote ($0.01), /api/v1/x402/fetch ($0.02), /api/v1/x402/chat ($0.02), /api/v1/feeds/{feed} ($0.01-$0.02; a free 24h-delayed edition sits at /api/v1/feeds/{feed}/sample). Long-running jobs: POST /api/v1/x402/run/{mode} ($0.25-$1.85 per run; the paying wallet becomes the account). Credit-billed account surface (API key, not x402): GET /api/v1/auth/config to discover the Supabase backend, sign up (email confirmation is off), POST /api/v1/agent/register, then POST /api/v1/account/api-keys for an sk_swarm_ key.'
  contact:
    url: https://ioswarm.io
    email: support@ioservices.io
servers:
- url: https://ioswarm.io
tags:
- name: Search
paths:
  /api/v1/search:
    get:
      operationId: searchGet
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.020000'
        protocols:
        - x402: {}
      summary: Keyless web search.
      security: []
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
        description: 'What to search for (alias: q).'
      - name: k
        in: query
        required: false
        schema:
          type: integer
        description: Results to return (default 8; the free leg clamps to 5, the paid leg to 20).
      - name: freshness
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - day
          - week
          - month
          - year
      - name: domains
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated domain allowlist, e.g. reuters.com,apnews.com.
      responses:
        '200':
          description: 'Answered. Free leg: organic results (≤5) plus a quota block. Paid leg: results (≤20) plus a paid block and the settlement header.'
        '402':
          description: 'Over the free quota — the payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED). A bare GET (no query parameter) always answers this challenge: the discovery document (free quota, body shape, bazaar extension) rides inside the 402 body, which is what directory validators (CDP /validate among them) read.'
        '400':
          description: Missing or oversized query when a payment header is present — refused before the facilitator is asked. Without a payment header the 402 quotes the price instead.
      tags:
      - Search
    post:
      operationId: searchPost
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.020000'
        protocols:
        - x402: {}
      summary: Same two legs as GET with a JSON body.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                k:
                  type: integer
                freshness:
                  type: string
                domains:
                  type: string
      parameters:
      - name: X-PAYMENT
        in: header
        required: false
        schema:
          type: string
        description: 'v1: the signed payment payload, base64.'
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        schema:
          type: string
        description: 'v2: the signed payment payload, base64.'
      responses:
        '200':
          description: Answered — free leg (quota block) or paid leg (paid block + settlement header).
        '402':
          description: Over the free quota — the payment requirements.
        '400':
          description: Missing or oversized query when a payment header is present — refused before the facilitator is asked. Without a payment header the 402 quotes the price instead.
      tags:
      - Search
  /api/v1/search/report:
    get:
      operationId: describeSearchReport
      summary: Describe this x402 primitive.
      security: []
      responses:
        '402':
          description: 'The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED) with the discovery document merged in: endpoint, price, POST body shape, response shape, the x402 how, and the bazaar extension.'
        '200':
          description: Machine payments are not configured — the plain discovery document, nothing to sell.
      tags:
      - Search
    post:
      operationId: searchReport
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.050000'
        protocols:
        - x402: {}
      summary: 'One-call research brief: live web search synthesized into a cited bullet report…'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                k:
                  type: integer
                  description: Results to synthesize (default 8, max 10).
                freshness:
                  type: string
                  enum:
                  - all
                  - day
                  - week
                  - month
                  - year
                domains:
                  type: string
                  description: Comma-separated domain allowlist.
      parameters:
      - name: X-PAYMENT
        in: header
        required: false
        schema:
          type: string
        description: 'v1: the signed payment payload, base64.'
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        schema:
          type: string
        description: 'v2: the signed payment payload, base64.'
      responses:
        '200':
          description: '{query, report, results (≤10), usage, paid block + settlement header}.'
        '402':
          description: The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED).
        '400':
          description: Missing or oversized query when a payment header is present — refused before the facilitator is asked. Without a payment header the 402 quotes the price instead.
        '502':
          description: Settled but the search backend or model did not answer — the transaction hash is quoted for support.
      tags:
      - Search
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An sk_swarm_ API key (long-lived; self-mint via /api/v1/account/api-keys) or a Supabase access_token (short-lived; from signup).