{"components":{"schemas":{"Agent":{"properties":{"agent":{"example":"eip155:8453:1203","type":"string"},"agent_id":{"type":"string"},"badge":{"type":"string"},"categories":{"items":{"type":"string"},"type":"array"},"chain":{"type":"string"},"enough_data":{"type":"boolean"},"groups":{"type":"object"},"label":{"enum":["Trusted","Good","Caution","Risky","Not enough data","Flagged"],"type":"string"},"name":{"type":["string","null"]},"owner_reputation":{"description":"Single-agent lookups only (Builder and higher; Free gets {locked: true}): what else the owner wallet runs, red flags and plain-language signals.","type":["object","null"]},"protocols":{"items":{"type":"string"},"type":"array"},"reasons":{"properties":{"down":{"items":{"type":"string"},"type":"array"},"up":{"items":{"type":"string"},"type":"array"}},"type":"object"},"reports":{"type":"object"},"score":{"description":"Null when the label is \"Not enough data\" (unknown, not low).","maximum":100,"minimum":0,"type":["integer","null"]},"url":{"type":"string"}},"type":"object"},"AgentList":{"properties":{"agents":{"items":{"type":"string"},"maxItems":500,"type":"array"}},"required":["agents"],"type":"object"},"Decision":{"properties":{"agent":{"$ref":"#/components/schemas/Agent"},"allow":{"type":"boolean"},"attestation":{"type":"object"},"checks":{"items":{"type":"string"},"type":"array"},"decision_id":{"type":"integer"},"delegation_chain":{"items":{"type":"string"},"type":"array"},"label":{"type":"string"},"principal":{"description":"With a delegation chain: the agent the request is ultimately made for.","type":["string","null"]},"reasons":{"items":{"type":"string"},"type":"array"},"score":{"type":["integer","null"]},"verified":{"type":"boolean"}},"type":"object"},"Error":{"properties":{"error":{"type":"string"}},"type":"object"}},"securitySchemes":{"bearer":{"description":"nep_\u2026 API key","scheme":"bearer","type":"http"}}},"externalDocs":{"url":"https://neptuv.xyz/docs"},"info":{"contact":{"url":"https://neptuv.xyz/contact"},"description":"Neptuv reads the public ERC-8004 registries and scores every AI agent from 0 to 100 with the reasons shown. Read endpoints work without a key on the free limits.","summary":"Trust scores, Know Your Agent verification and allow/deny policies for ERC-8004 AI agents.","termsOfService":"https://neptuv.xyz/terms","title":"Neptuv API","version":"2.0.0"},"openapi":"3.1.0","paths":{"/agents/batch":{"post":{"operationId":"batchAgents","requestBody":{"content":{"application/json":{"schema":{"properties":{"agents":{"items":{"oneOf":[{"type":"string"},{"properties":{"agent":{"description":"CAIP-style agent reference.","example":"eip155:8453:1203","type":"string"},"agent_id":{"example":"1203","type":"string"},"chain":{"example":"base","type":"string"}},"type":"object"}]},"maxItems":100,"type":"array"}},"required":["agents"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"items":{"$ref":"#/components/schemas/Agent"},"type":"array"}},"type":"object"}}},"description":"OK"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Up to 100 agents per call (Pro)","tags":["Agents"]}},"/agents/{chain}/{agent_id}":{"get":{"operationId":"getAgent","parameters":[{"description":"Chain slug (ethereum, base, arbitrum, optimism, polygon, \u2026).","example":"base","in":"path","name":"chain","required":true,"schema":{"type":"string"}},{"description":"ERC-8004 agent ID.","example":"1203","in":"path","name":"agent_id","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}},"description":"OK"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Full agent profile with score and reasons","tags":["Agents"]}},"/agents/{chain}/{agent_id}/incidents":{"get":{"operationId":"getAgentIncidents","parameters":[{"description":"Chain slug (ethereum, base, arbitrum, optimism, polygon, \u2026).","example":"base","in":"path","name":"chain","required":true,"schema":{"type":"string"}},{"description":"ERC-8004 agent ID.","example":"1203","in":"path","name":"agent_id","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Confirmed reports about an agent","tags":["Network"]}},"/agents/{chain}/{agent_id}/score":{"get":{"operationId":"getScore","parameters":[{"description":"Chain slug (ethereum, base, arbitrum, optimism, polygon, \u2026).","example":"base","in":"path","name":"chain","required":true,"schema":{"type":"string"}},{"description":"ERC-8004 agent ID.","example":"1203","in":"path","name":"agent_id","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}},"description":"OK"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Score, label, groups and reasons","tags":["Agents"]}},"/attest":{"post":{"operationId":"attestAgent","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"properties":{"agent":{"description":"CAIP-style agent reference.","example":"eip155:8453:1203","type":"string"},"agent_id":{"example":"1203","type":"string"},"chain":{"example":"base","type":"string"}},"type":"object"},{"properties":{"ttl":{"default":3600,"maximum":86400,"minimum":60,"type":"integer"}},"type":"object"}]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Signed EIP-712 trust attestation (Platform)","tags":["Decisions"]}},"/attester":{"get":{"operationId":"getAttester","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"security":[{}],"summary":"Neptuv's attester address and EIP-712 domain","tags":["Decisions"]}},"/decisions":{"get":{"operationId":"listDecisions","parameters":[{"in":"query","name":"kind","schema":{"enum":["gate","verify","mcp"],"type":"string"}},{"in":"query","name":"allow","schema":{"enum":["1","0"],"type":"string"}},{"in":"query","name":"agent","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"maximum":500,"type":"integer"}},{"in":"query","name":"offset","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Your decision log (Pro)","tags":["Account"]}},"/export/agents.{format}":{"get":{"operationId":"exportAgents","parameters":[{"in":"path","name":"format","required":true,"schema":{"enum":["csv","json"],"type":"string"}}],"responses":{"200":{"description":"OK"}},"summary":"Every scored agent (Platform)","tags":["Network"]}},"/flags":{"get":{"operationId":"listFlags","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Risky and flagged agents (Platform)","tags":["Network"]}},"/gate":{"post":{"operationId":"gateAgent","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"properties":{"agent":{"description":"CAIP-style agent reference.","example":"eip155:8453:1203","type":"string"},"agent_id":{"example":"1203","type":"string"},"chain":{"example":"base","type":"string"}},"type":"object"},{"properties":{"allow_agents":{"example":["base:1203"],"items":{"type":"string"},"type":"array"},"allow_labels":{"items":{"enum":["Trusted","Good","Caution","Risky","Not enough data","Flagged"],"type":"string"},"type":"array"},"allow_not_enough_data":{"default":false,"type":"boolean"},"block_flagged":{"default":true,"type":"boolean"},"chains":{"items":{"type":"string"},"type":"array"},"deny_agents":{"items":{"type":"string"},"type":"array"},"max_open_reports":{"minimum":1,"type":["integer","null"]},"min_age_days":{"default":0,"minimum":0,"type":"integer"},"min_score":{"default":60,"maximum":100,"minimum":0,"type":"integer"},"require_validations":{"default":0,"minimum":0,"type":"integer"},"require_verified_domain":{"default":false,"type":"boolean"}},"type":"object"},{"properties":{"policy":{"description":"Saved policy ID (default: your default policy).","type":"integer"}},"type":"object"}]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Decision"}}},"description":"OK"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Allow or deny an agent with your policy (Pro)","tags":["Decisions"]}},"/incidents":{"get":{"operationId":"listMyIncidents","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Reports your workspace filed (Pro)","tags":["Network"]},"post":{"operationId":"reportAgent","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"properties":{"agent":{"description":"CAIP-style agent reference.","example":"eip155:8453:1203","type":"string"},"agent_id":{"example":"1203","type":"string"},"chain":{"example":"base","type":"string"}},"type":"object"},{"properties":{"category":{"enum":["fraud","non_delivery","impersonation","abuse","data","security","other"],"type":"string"},"evidence":{"description":"https:// link or 0x transaction hash","type":"string"},"severity":{"enum":["low","medium","high","critical"],"type":"string"},"summary":{"maxLength":2000,"minLength":30,"type":"string"}},"required":["category","severity","summary"],"type":"object"}]}}},"required":true},"responses":{"201":{"description":"Created"}},"summary":"Report an agent (Pro)","tags":["Network"]}},"/policies":{"get":{"operationId":"listPolicies","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Your saved policies (Pro)","tags":["Account"]}},"/search":{"get":{"operationId":"searchAgents","parameters":[{"in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"chain","schema":{"type":"string"}},{"in":"query","name":"category","schema":{"enum":["research","trading-defi","coding","support","data","content","payments","security","productivity","infrastructure"],"type":"string"}},{"in":"query","name":"protocol","schema":{"enum":["mcp","a2a","web","oasf","ens","did","x402","email"],"type":"string"}},{"in":"query","name":"min_score","schema":{"maximum":100,"minimum":0,"type":"integer"}},{"in":"query","name":"label","schema":{"enum":["trusted","good","caution","risky","unknown","flagged"],"type":"string"}},{"in":"query","name":"sort","schema":{"enum":["score","reviews","newest","oldest"],"type":"string"}},{"in":"query","name":"limit","schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"items":{"$ref":"#/components/schemas/Agent"},"type":"array"},"total":{"type":"integer"}},"type":"object"}}},"description":"OK"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Search and filter agents","tags":["Agents"]}},"/stats":{"get":{"operationId":"getStats","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Network-wide numbers","tags":["Network"]}},"/verify":{"post":{"operationId":"verifyAgentRequest","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"properties":{"allow_agents":{"example":["base:1203"],"items":{"type":"string"},"type":"array"},"allow_labels":{"items":{"enum":["Trusted","Good","Caution","Risky","Not enough data","Flagged"],"type":"string"},"type":"array"},"allow_not_enough_data":{"default":false,"type":"boolean"},"block_flagged":{"default":true,"type":"boolean"},"chains":{"items":{"type":"string"},"type":"array"},"deny_agents":{"items":{"type":"string"},"type":"array"},"max_open_reports":{"minimum":1,"type":["integer","null"]},"min_age_days":{"default":0,"minimum":0,"type":"integer"},"min_score":{"default":60,"maximum":100,"minimum":0,"type":"integer"},"require_validations":{"default":0,"minimum":0,"type":"integer"},"require_verified_domain":{"default":false,"type":"boolean"}},"type":"object"},{"properties":{"attest":{"type":"boolean"},"body_sha256":{"pattern":"^[0-9a-f]{64}$","type":"string"},"delegation":{"description":"Delegation chain when the agent acts for another agent: erc8004-delegation/1 tokens, root first, comma-separated.","type":"string"},"headers":{"description":"The Neptuv-Agent, -Timestamp, -Nonce and -Signature headers (and Neptuv-Delegation or ERC8004-Delegation, if any).","type":"object"},"method":{"example":"POST","type":"string"},"policy":{"type":"integer"},"url":{"format":"uri","type":"string"}},"required":["method","url","headers"],"type":"object"}]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Decision"}}},"description":"OK"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Know Your Agent: verify a signed agent request, then apply your policy (Pro)","tags":["Decisions"]}},"/watchlist":{"delete":{"operationId":"unwatchAgents","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentList"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Stop following agents","tags":["Account"]},"get":{"operationId":"listWatchlist","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Agents you follow (Pro)","tags":["Account"]},"post":{"operationId":"watchAgents","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentList"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Follow agents (Pro)","tags":["Account"]}}},"security":[{"bearer":[]},{}],"servers":[{"url":"https://neptuv.xyz/api/v1"}],"tags":[{"name":"Agents"},{"name":"Decisions"},{"name":"Network"},{"name":"Account"}]}