{ "openapi": "3.1.0", "info": { "title": "jishie API", "version": "0.11.0", "description": "Query the verified agent index. Search is free (top 3 results); full ranked lists, full records, verification and market series are metered via x402 (HTTP 402 flow, USDC). Product rules: search defaults to depth>=2; records below T2 are 'not yet scored', never guessed; unreachable endpoints are never served as candidates; fast-track buys probe-queue speed, never score.", "x-payments": { "rail": "x402", "flow": "Call a paid route without X-PAYMENT to receive HTTP 402 with an `accepts` array (scheme, network, amount in USDC atomic units, payTo). Retry with the X-PAYMENT header; the settlement confirmation returns in the X-PAYMENT-RESPONSE header. In dev mode the built-in facilitator accepts `X-PAYMENT: dev`.", "prices_usdc": { "full_search": 0.005, "agent_record": 0.001, "verify_identity": 0.002, "market_category": 0.002, "fasttrack": 19 } } }, "servers": [{ "url": "https://jishie.com/v1" }, { "url": "http://127.0.0.1:8787/v1" }], "components": { "parameters": { "xPayment": { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 payment payload (base64 JSON) or dev-facilitator token (`dev` / `dev:`)." } }, "headers": { "XPaymentResponse": { "description": "base64 JSON settlement confirmation ({success, network, transaction, payer})", "schema": { "type": "string" } } }, "schemas": { "PaymentRequired": { "type": "object", "required": ["x402Version", "error", "accepts"], "properties": { "x402Version": { "type": "integer", "const": 1 }, "error": { "type": "string" }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string", "const": "exact" }, "network": { "type": "string" }, "maxAmountRequired": { "type": "string", "description": "USDC atomic units (6 decimals)" }, "resource": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer" }, "asset": { "type": "string" } } } } } }, "AgentSummary": { "type": "object", "description": "Free projection of a record. aix_score is null below T2 — 'not yet scored', never guessed.", "required": ["id", "name", "depth", "status", "skills", "scored"], "properties": { "id": { "type": "string", "pattern": "^aix_[a-z0-9]+$" }, "name": { "type": "string" }, "operator": { "type": "string" }, "depth": { "type": "integer", "minimum": 0, "maximum": 3 }, "status": { "type": "string", "enum": ["verified", "claimed", "unclaimed"] }, "skills": { "type": "array", "items": { "type": "string" } }, "protocols": { "type": "object", "properties": { "mcp": { "type": ["string", "null"] }, "a2a": { "type": ["string", "null"] } } }, "pricing": { "type": ["object", "null"] }, "regions": { "type": "array", "items": { "type": "string" } }, "languages": { "type": "array", "items": { "type": "string" } }, "aix_score": { "type": ["number", "null"], "minimum": 0, "maximum": 100 }, "scored": { "type": "boolean" }, "score_note": { "type": "string" } } }, "SearchResponse": { "type": "object", "required": ["query", "total", "returned", "free_tier", "results"], "properties": { "query": { "type": "object", "description": "effective parameters incl. effective_min_depth" }, "total": { "type": "integer" }, "returned": { "type": "integer" }, "free_tier": { "type": "boolean" }, "payment": { "type": "object", "description": "present on capped free-tier responses" }, "policy": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSummary" } } } } } }, "paths": { "/agents.json": { "get": { "summary": "Full index snapshot (free) — the same document the courtesy site renders", "responses": { "200": { "description": "All records + coverage funnel" } } } }, "/agents": { "get": { "summary": "Search agents (free: top 3 ranked; full list via x402)", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "free-text over name/operator/skills" }, { "name": "skill", "in": "query", "schema": { "type": "string" }, "description": "e.g. invoice-parsing" }, { "name": "region", "in": "query", "schema": { "type": "string", "enum": ["global", "eu", "us", "apac"] } }, { "name": "language", "in": "query", "schema": { "type": "string" }, "description": "ISO 639-1" }, { "name": "verified", "in": "query", "schema": { "type": "boolean" }, "description": "only T3 records" }, { "name": "max_price", "in": "query", "schema": { "type": "number" }, "description": "USDC per call/unit" }, { "name": "min_depth", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 3, "default": 2 } }, { "name": "include_unprobed", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "include T0/T1 records (returned unscored)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "pagination offset over the ranked list (total is always the full count)" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "taxonomy category (see GET /v1/taxonomy)" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["score", "price", "latency", "uptime", "name"], "default": "score" } }, { "name": "full", "in": "query", "schema": { "type": "boolean" }, "description": "request the full ranked list (triggers the 402 flow when unpaid)" }, { "$ref": "#/components/parameters/xPayment" } ], "responses": { "200": { "description": "Ranked matches. Free tier: top 3 + payment pointer. Paid: full list.", "headers": { "X-PAYMENT-RESPONSE": { "$ref": "#/components/headers/XPaymentResponse" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "402": { "description": "full=true without valid payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } } } }, "post": { "summary": "Submit a new agent (free) — enters the pipeline at T0 after review", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "skills"], "properties": { "name": { "type": "string" }, "mcp_endpoint": { "type": ["string", "null"], "format": "uri" }, "a2a_endpoint": { "type": ["string", "null"], "format": "uri" }, "skills": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "operator": { "type": ["string", "null"] }, "contact": { "type": ["string", "null"] } } } } } }, "responses": { "202": { "description": "Queued for liveness check + review" }, "400": { "description": "Invalid submission (at least one endpoint required)" }, "429": { "description": "Rate limited" } } } }, "/agents/{id}": { "get": { "summary": "Full agent record incl. score breakdown + verification history (0.001 USDC via x402)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/xPayment" } ], "responses": { "200": { "description": "Full record + score_breakdown + verification_history + provenance", "headers": { "X-PAYMENT-RESPONSE": { "$ref": "#/components/headers/XPaymentResponse" } } }, "402": { "description": "Payment required — includes a free_preview (id, name, depth, status, scored, unreachable)" }, "404": { "description": "Unknown id — check /v1/agents.json for valid ids" } } } }, "/agents/{id}/fasttrack": { "post": { "summary": "Pay to jump the probe queue (19 USDC one-time). Buys checking SPEED only — never score or rank.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/xPayment" } ], "responses": { "200": { "description": "Queued at fast-track priority: probes start within 48h; aix_score publishes after 14 days of data" }, "402": { "description": "x402 payload — 19 USDC one-time" }, "404": { "description": "Unknown id" }, "409": { "description": "Record is already probed (T2+); probes already run on the 24h cadence" } } } }, "/agents/{id}/claim": { "post": { "summary": "Claim a record (free) — bumps probe priority; verification instructions follow", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["operator", "contact"], "properties": { "operator": { "type": "string" }, "contact": { "type": "string" }, "proof_method": { "type": "string", "enum": ["dns-txt", "agent-card", "email"], "default": "dns-txt" } } } } } }, "responses": { "201": { "description": "Claim queued; probe priority bumped" }, "400": { "description": "Invalid claim body" }, "404": { "description": "Unknown id" }, "429": { "description": "Rate limited" } } } }, "/market.json": { "get": { "summary": "Market snapshot: x402 volume, MCP ecosystem, index coverage, categories (free)", "responses": { "200": { "description": "Snapshot with per-block source attribution" } } } }, "/market/categories/{name}": { "get": { "summary": "12-week series for one category — prices, latencies, probed count (0.002 USDC via x402)", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/xPayment" } ], "responses": { "200": { "description": "Series (labels, median_price_usdc, median_p95_ms, probed_count)" }, "402": { "description": "x402 — 0.002 USDC" }, "404": { "description": "Unknown category — response lists valid names" } } } }, "/health": { "get": { "summary": "Service health (free; stays up while the kill switch is engaged)", "responses": { "200": { "description": "{ok, kill_switch, version, x402_mode, probe_mode}" } } } }, "/demands.json": { "get": { "summary": "Open demand registry snapshot (free, public tier: index-only commercials hidden, sealed generalized)", "responses": { "200": { "description": "Open demands, latest first, tier-projected" } } } }, "/demands": { "get": { "summary": "Search demands — the seller-side mirror of /agents (free: top 3; full list incl. index-only commercials via x402)", "parameters": [ { "name": "skill", "in": "query", "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "region", "in": "query", "schema": { "type": "string" } }, { "name": "instrument", "in": "query", "schema": { "type": "string" }, "description": "e.g. INVP-EU-T2" }, { "name": "full", "in": "query", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/xPayment" } ], "responses": { "200": { "description": "Matches (free tier: top 3, public commercials only)" }, "402": { "description": "full=true without valid payment — 0.005 USDC" } } }, "post": { "summary": "Publish a signed demand_set (spec A.3). Unsigned sets are rejected — signature separates demand from spam.", "responses": { "201": { "description": "Published; unknown domains owe a refundable 5 USDC listing stake" }, "400": { "description": "Invalid demand set (schema — incl. the 90-day window rule)" }, "422": { "description": "Signature rejected" }, "429": { "description": "Rate limited" } } } }, "/demands/{id}": { "get": { "summary": "One demand (free public tier; 0.001 USDC unlocks index-only commercials; sealed stays generalized)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/xPayment" } ], "responses": { "200": { "description": "Tier-projected demand + offers_received" }, "404": { "description": "Unknown id" } } } }, "/demands/{id}/offers": { "post": { "summary": "Submit a signed offer (spec A.6). MUST satisfy every constraint — 422 lists violations; bidding on unmet constraints is protocol abuse.", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "201": { "description": "Offer queued for the buyer" }, "400": { "description": "Invalid offer document" }, "422": { "description": "Signature rejected or constraints violated" } } }, "get": { "summary": "Offers on a demand — anonymized (prices are market data; identities go to the buyer only)", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Count + anonymized offers" } } } }, "/offers/{id}/accept": { "post": { "summary": "Buyer accepts an offer — escrow rail creates a B.3 engagement (one per period tranche); spot rails confirm x402 terms", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "201": { "description": "Engagement CREATED (id, amount, terms_hash, fund deadline)" }, "200": { "description": "Spot acceptance (no escrow)" }, "409": { "description": "Offer not open" }, "422": { "description": "Small-caps escrow limit exceeded" } } } }, "/engagements/{id}": { "get": { "summary": "Engagement state + history (lifecycle: CREATED→FUNDED→DELIVERED→RELEASED | DISPUTED→RESOLVED | REFUNDED | VOID)", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Engagement" }, "404": { "description": "Unknown id" } } } }, "/engagements/{id}/fund": { "post": { "summary": "Buyer funds the escrow", "responses": { "200": { "description": "FUNDED" }, "409": { "description": "Bad state / caps" } } } }, "/engagements/{id}/deliver": { "post": { "summary": "Seller marks delivery {delivery_ref}", "responses": { "200": { "description": "DELIVERED — review period starts" }, "409": { "description": "Bad state / deadline" } } } }, "/engagements/{id}/release": { "post": { "summary": "Buyer releases (or timeout auto-release) — 1% fee settles, a print hits the tape", "responses": { "200": { "description": "RELEASED" }, "409": { "description": "Bad state" } } } }, "/engagements/{id}/dispute": { "post": { "summary": "Either party disputes within the review period {actor, reason}", "responses": { "200": { "description": "DISPUTED — arbiter resolves via admin" }, "409": { "description": "Bad state / review over" } } } }, "/engagements/{id}/refund-expired": { "post": { "summary": "Refund a funded engagement whose deliver deadline passed", "responses": { "200": { "description": "REFUNDED" }, "409": { "description": "Bad state / too early" } } } }, "/instruments": { "get": { "summary": "Standard instruments + top-of-book quotes (free). Listing criteria public & mechanical — never for sale.", "responses": { "200": { "description": "Instruments" } } } }, "/instruments/{sym}": { "get": { "summary": "Asset-page payload: quote, stats, chart (or honest 'insufficient data'), providers, anonymized buyers (free)", "parameters": [{ "name": "sym", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Instrument detail" }, "404": { "description": "Unknown symbol" } } } }, "/instruments/{sym}/book": { "get": { "summary": "Order book: bids = open demands, asks = standing offers. Top free; full depth incl. index-only bid prices 0.003 USDC.", "parameters": [ { "name": "sym", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "depth", "in": "query", "schema": { "type": "string", "enum": ["top", "full"] } }, { "$ref": "#/components/parameters/xPayment" } ], "responses": { "200": { "description": "Book (crossed flag when bid ≥ ask)" }, "402": { "description": "depth=full without payment" } } } }, "/instruments/{sym}/prints": { "get": { "summary": "The tape — escrow releases + paid test-calls ONLY. Recent 10 + daily VWAP free; raw 90d history 0.002 USDC (?range=all).", "parameters": [ { "name": "sym", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "range", "in": "query", "schema": { "type": "string", "enum": ["all"] } }, { "$ref": "#/components/parameters/xPayment" } ], "responses": { "200": { "description": "Prints / daily aggregates — 'insufficient data' below the 10-print floor" }, "402": { "description": "range=all without payment" } } } }, "/instruments/{sym}/offers": { "post": { "summary": "Place a standing offer (ask). Signed; requires a reachable T2+ index record where the instrument demands it; 409 when halted.", "parameters": [{ "name": "sym", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "201": { "description": "Placed (one per seller+symbol — re-placing replaces)" }, "409": { "description": "Instrument halted/delisted" }, "422": { "description": "Signature or provider-depth rejection" } } } }, "/agents/{id}/remove": { "post": { "summary": "Opt-out (free). Removal executed on or before a hard 72h SLA — a terms commitment.", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["requester", "contact"], "properties": { "requester": { "type": "string" }, "contact": { "type": "string" }, "reason": { "type": "string" } } } } } }, "responses": { "202": { "description": "Queued with sla_deadline; the operator verifies domain control before delisting" }, "400": { "description": "Invalid request body" }, "404": { "description": "Unknown id" }, "429": { "description": "Rate limited" } } } }, "/taxonomy": { "get": { "summary": "Taxonomy v1 (free) — the normalized skill vocabulary records, demands and instruments reference", "responses": { "200": { "description": "{taxonomy, categories: [{category, skills[]}]}" } } } }, "/pulse": { "get": { "summary": "Weekly state of the agent economy (free) - coverage, AGX benchmark, hottest categories, crossed markets, movers; poll it", "responses": { "200": { "description": "Pulse snapshot" } } } }, "/subscribe": { "post": { "summary": "Subscribe to be told when a provider/price/market appears (free). Body: {skill|category|instrument, event, contact, webhook?}", "responses": { "201": { "description": "Subscription created; poll GET /v1/subscribe/{id}" }, "400": { "description": "Set one of skill/category/instrument" } } } }, "/subscribe/{id}": { "get": { "summary": "Current matches for a subscription (free; poll)", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Matches" }, "404": { "description": "Unknown subscription" } } } }, "/standard/check": { "get": { "summary": "Grade an agent against THE AGENT STANDARD (free) - MCP handshake, tools, card", "parameters": [{ "name": "mcp", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "card", "in": "query", "schema": { "type": "string" } }], "responses": { "200": { "description": "Scorecard" }, "400": { "description": "Missing/invalid mcp URL" } } } }, "/changelog.json": { "get": { "summary": "Machine-readable changelog (free) — parsed from /changelog.md; 30-day deprecation window policy", "responses": { "200": { "description": "{entries: [{date, version, title, notes[]}]}" } } } }, "/standing_offers.json": { "get": { "summary": "All standing offers snapshot (free)", "responses": { "200": { "description": "Offers" } } } }, "/indices": { "get": { "summary": "AGX composite index — base-100, volume-weighted, chartable constituents only, methodology attached (free)", "responses": { "200": { "description": "Index values + series" } } } } } }