{"openapi":"3.1.0","info":{"title":"Agent Social Intelligence API","version":"1.0.0","description":"Paid, evidence-backed public social intelligence for AI agents."},"tags":[{"name":"Discovery","description":"Free service and contract discovery"},{"name":"Paid intelligence","description":"x402-protected intelligence"}],"paths":{"/":{"get":{"operationId":"getLandingPage","tags":["Discovery"],"responses":{"200":{"description":"Dependency-free HTML discovery page","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/docs":{"get":{"operationId":"getDocumentation","tags":["Discovery"],"responses":{"200":{"description":"Dependency-free HTML discovery page","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApi","tags":["Discovery"],"responses":{"200":{"description":"OpenAPI 3.1 document for the active runtime","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/pricing":{"get":{"operationId":"getPricing","tags":["Discovery"],"responses":{"200":{"description":"Current prices, Credit limits, and active payment network","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/healthz":{"get":{"operationId":"getHealth","tags":["Discovery"],"responses":{"200":{"description":"Worker liveness"}}}},"/readyz":{"get":{"operationId":"getReadiness","tags":["Discovery"],"responses":{"200":{"description":"Provider is usable and above execution reserve"},"503":{"description":"Provider unavailable or underfunded"},"504":{"description":"Provider preflight timed out"}}}},"/.well-known/agent-skills/index.json":{"get":{"operationId":"getAgentSkills","tags":["Discovery"],"responses":{"200":{"description":"Machine-readable Agent Skills discovery","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/terms":{"get":{"operationId":"getTerms","tags":["Discovery"],"responses":{"200":{"description":"Dependency-free HTML discovery page","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/privacy":{"get":{"operationId":"getPrivacy","tags":["Discovery"],"responses":{"200":{"description":"Dependency-free HTML discovery page","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/acceptable-use":{"get":{"operationId":"getAcceptableUse","tags":["Discovery"],"responses":{"200":{"description":"Dependency-free HTML discovery page","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/contact":{"get":{"operationId":"getContact","tags":["Discovery"],"responses":{"200":{"description":"Dependency-free HTML discovery page","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/v1/search/social":{"post":{"operationId":"search_social","summary":"Search and normalize up to 25 recent public X signals.","tags":["Paid intelligence"],"x-x402-price-usd":"0.01","x-x402-network":"eip155:84532","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"additionalProperties":false,"properties":{"query":{"type":"string","minLength":2,"maxLength":256},"platforms":{"type":"array","minItems":1,"maxItems":1,"items":{"const":"x"},"default":["x"]},"time_range":{"type":"object","additionalProperties":false,"required":["from","to"],"description":"from must precede to; maximum span is 30 days","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"languages":{"type":"array","maxItems":3,"default":[],"items":{"type":"string","description":"BCP-47 language tag"}},"sort":{"enum":["relevance","recent"],"default":"relevance"},"limit":{"type":"integer","minimum":1,"maximum":25,"default":20},"safe_search":{"enum":["strict","moderate"],"default":"moderate"},"request_context":{"type":"object","additionalProperties":false,"properties":{"client_request_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,128}$"},"locale":{"type":"string","default":"en-US"},"max_latency_ms":{"type":"integer","minimum":3000,"maximum":45000,"default":30000},"allow_partial":{"type":"boolean","default":true}}}}}}}},"responses":{"200":{"description":"Evidence-backed intelligence response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelligenceResponse"}}}},"400":{"description":"Invalid request"},"402":{"description":"x402 payment challenge"},"403":{"description":"Policy blocked"},"503":{"description":"Provider unavailable or budget exhausted"},"504":{"description":"Provider or analysis timeout"}}}},"/v1/intelligence/user":{"post":{"operationId":"user_intelligence","summary":"Evidence-backed intelligence for one public X account.","tags":["Paid intelligence"],"x-x402-price-usd":"0.02","x-x402-network":"eip155:84532","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["account"],"additionalProperties":false,"properties":{"account":{"type":"string","description":"X handle or public profile URL"},"lookback_days":{"type":"integer","minimum":1,"maximum":30,"default":30},"languages":{"type":"array","maxItems":3,"default":[],"items":{"type":"string","description":"BCP-47 language tag"}},"max_items":{"type":"integer","minimum":1,"maximum":50,"default":40},"include_network_signals":{"const":false,"default":false},"request_context":{"type":"object","additionalProperties":false,"properties":{"client_request_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,128}$"},"locale":{"type":"string","default":"en-US"},"max_latency_ms":{"type":"integer","minimum":3000,"maximum":45000,"default":30000},"allow_partial":{"type":"boolean","default":true}}}}}}}},"responses":{"200":{"description":"Evidence-backed intelligence response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelligenceResponse"}}}},"400":{"description":"Invalid request"},"402":{"description":"x402 payment challenge"},"403":{"description":"Policy blocked"},"503":{"description":"Provider unavailable or budget exhausted"},"504":{"description":"Provider or analysis timeout"}}}},"/v1/intelligence/topic":{"post":{"operationId":"topic_intelligence","summary":"Trends, themes, controversies, and sources for one topic.","tags":["Paid intelligence"],"x-x402-price-usd":"0.05","x-x402-network":"eip155:84532","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["topic"],"additionalProperties":false,"properties":{"topic":{"type":"string","minLength":2,"maxLength":256},"lookback_days":{"type":"integer","minimum":1,"maximum":14,"default":14},"platforms":{"type":"array","minItems":1,"maxItems":1,"items":{"const":"x"},"default":["x"]},"languages":{"type":"array","maxItems":3,"default":[],"items":{"type":"string","description":"BCP-47 language tag"}},"focus":{"type":"array","maxItems":8,"default":[],"items":{"type":"string","minLength":1,"maxLength":64}},"max_sources":{"type":"integer","minimum":20,"maximum":100,"default":80},"request_context":{"type":"object","additionalProperties":false,"properties":{"client_request_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,128}$"},"locale":{"type":"string","default":"en-US"},"max_latency_ms":{"type":"integer","minimum":3000,"maximum":45000,"default":30000},"allow_partial":{"type":"boolean","default":true}}}}}}}},"responses":{"200":{"description":"Evidence-backed intelligence response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelligenceResponse"}}}},"400":{"description":"Invalid request"},"402":{"description":"x402 payment challenge"},"403":{"description":"Policy blocked"},"503":{"description":"Provider unavailable or budget exhausted"},"504":{"description":"Provider or analysis timeout"}}}},"/v1/intelligence/product":{"post":{"operationId":"product_intelligence","summary":"Evidence-backed product feedback, pain points, and competitor signals.","tags":["Paid intelligence"],"x-x402-price-usd":"0.10","x-x402-network":"eip155:84532","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product"],"additionalProperties":false,"properties":{"product":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"url":{"type":"string","format":"uri","pattern":"^https://"}}},"competitors":{"type":"array","maxItems":5,"items":{"type":"string","minLength":1,"maxLength":120},"default":[]},"lookback_days":{"type":"integer","minimum":1,"maximum":30,"default":30},"focus":{"type":"array","maxItems":4,"default":[],"items":{"enum":["bugs","pricing","feature_requests","switching"]}},"languages":{"type":"array","maxItems":3,"default":[],"items":{"type":"string","description":"BCP-47 language tag"}},"max_sources":{"type":"integer","minimum":20,"maximum":150,"default":120},"request_context":{"type":"object","additionalProperties":false,"properties":{"client_request_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,128}$"},"locale":{"type":"string","default":"en-US"},"max_latency_ms":{"type":"integer","minimum":3000,"maximum":45000,"default":30000},"allow_partial":{"type":"boolean","default":true}}}}}}}},"responses":{"200":{"description":"Evidence-backed intelligence response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelligenceResponse"}}}},"400":{"description":"Invalid request"},"402":{"description":"x402 payment challenge"},"403":{"description":"Policy blocked"},"503":{"description":"Provider unavailable or budget exhausted"},"504":{"description":"Provider or analysis timeout"}}}}},"components":{"schemas":{"IntelligenceResponse":{"type":"object","additionalProperties":false,"required":["request_id","tool","schema_version","status","generated_at","data_window","summary","data","insights","sources","coverage","warnings","billing","meta"],"properties":{"request_id":{"type":"string","pattern":"^asi_req_[A-Za-z0-9_-]+$"},"client_request_id":{"type":"string","minLength":1,"maxLength":128},"tool":{"enum":["search_social","user_intelligence","topic_intelligence","product_intelligence"]},"schema_version":{"const":"2026-08-14"},"status":{"enum":["ok","partial","no_data"]},"generated_at":{"type":"string","format":"date-time"},"data_window":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"summary":{"type":"string"},"data":{"type":"object","additionalProperties":true},"insights":{"type":"array","items":{"type":"object","required":["id","type","statement","confidence","evidence_source_ids"],"properties":{"id":{"type":"string"},"type":{"type":"string"},"statement":{"type":"string"},"confidence":{"type":"object","additionalProperties":true},"evidence_source_ids":{"type":"array","items":{"type":"string"}}}}},"sources":{"type":"array","items":{"type":"object","required":["id","platform","type","external_id","url","published_at","retrieved_at","author_external_id","title","excerpt"],"properties":{"id":{"type":"string"},"platform":{"const":"x"},"type":{"enum":["post","profile"]},"external_id":{"type":"string"},"url":{"type":"string","format":"uri"},"published_at":{"type":["string","null"],"format":"date-time"},"retrieved_at":{"type":"string","format":"date-time"},"author_external_id":{"type":["string","null"]},"title":{"type":["string","null"]},"excerpt":{"type":"null"}}}},"coverage":{"type":"object","required":["level","items_examined","items_used","providers_attempted","providers_succeeded","languages"],"properties":{"level":{"enum":["low","medium","high"]},"items_examined":{"type":"integer","minimum":0},"items_used":{"type":"integer","minimum":0},"providers_attempted":{"type":"integer","minimum":0},"providers_succeeded":{"type":"integer","minimum":0},"languages":{"type":"array","items":{"type":"string"}}}},"warnings":{"type":"array","items":{"type":"string"}},"billing":{"type":"object","required":["price_usd","network","payment_status","payment_id","settlement_reference"],"properties":{"price_usd":{"type":"string","pattern":"^[0-9]+\\.[0-9]{2}$"},"network":{"enum":["eip155:84532","eip155:8453"]},"payment_status":{"enum":["settlement_pending","settled"]},"payment_id":{"type":["string","null"]},"settlement_reference":{"type":["string","null"]}}},"meta":{"type":"object","required":["cache","processing_ms","provider_credits_used"],"properties":{"cache":{"enum":["hit","miss"]},"processing_ms":{"type":"integer","minimum":0},"provider_credits_used":{"type":"integer","minimum":0}}}}}}}}