{"openapi":"3.1.0","info":{"title":"Reevol Source REST API","version":"1.2.0","description":"Public REST API over the Reevol Source supplier intelligence platform, part of Reevol, the Revenue OS for Global Trade. Powering the agentic era of global trade. Mirrors the MCP tool surface at https://source.reevol.com/mcp for partners who prefer REST. Anonymous, rate-limited at 60 requests per minute per IP. For per-supplier auth (claim ownership, edit profile, see leads) use Reevi at https://compass.reevol.com.","contact":{"name":"Reevol","url":"https://source.reevol.com/for-agents/"},"license":{"name":"See terms at https://source.reevol.com/terms/"}},"servers":[{"url":"https://source.reevol.com/api/v1"}],"paths":{"/suppliers/match":{"post":{"summary":"Match suppliers from a freeform buyer brief + structured filters","description":"Combines Voyage semantic search (over supplier industry, HS codes, certifications, trade-fair history, and the EN summary) with structured filters. Returns ranked supplier cards each carrying a `matchExplanation` describing why it was included.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchRequest"}}}},"responses":{"200":{"description":"Ranked supplier cards","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchResponse"}}}},"400":{"description":"Brief missing or too short"}}}},"/suppliers/search":{"get":{"summary":"Search suppliers by name, brand, or alias","parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200},"description":"Company name, brand, or alias (min 2 chars)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10}},{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":"Locale for the returned URLs."}],"responses":{"200":{"description":"List of matching suppliers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierList"}}}}}}},"/suppliers/by-hs-code/{hsCode}":{"get":{"summary":"Find suppliers by HS code","parameters":[{"name":"hsCode","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{2}$|^\\d{4}$|^\\d{6}$"},"description":"HS code (2, 4, or 6 digits)."},{"name":"country","in":"query","required":false,"schema":{"type":"string"},"description":"Canonical country name filter (e.g. \"China\")."},{"name":"certifications","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated certifications (any-of). E.g. \"ISO 9001,BSCI\"."},{"name":"employeeRange","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated employee bands."},{"name":"businessType","in":"query","required":false,"schema":{"type":"string","enum":["manufacturer","trading_company","any"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10}},{"name":"lang","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of matching suppliers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierList"}}}}}}},"/suppliers/by-country/{country}":{"get":{"summary":"Find suppliers in a country","parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string"}},{"name":"industry","in":"query","required":false,"schema":{"type":"string"}},{"name":"certifications","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated certifications (any-of)."},{"name":"employeeRange","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated employee bands."},{"name":"businessType","in":"query","required":false,"schema":{"type":"string","enum":["manufacturer","trading_company","any"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10}},{"name":"lang","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of matching suppliers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierList"}}}}}}},"/suppliers/{slug}":{"get":{"summary":"Full supplier profile","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":"Locale for summary + FAQ."}],"responses":{"200":{"description":"Supplier profile","content":{"application/json":{"schema":{"type":"object","properties":{"supplier":{"$ref":"#/components/schemas/SupplierProfile"}}}}}},"404":{"description":"Supplier not found"}}}},"/suppliers/{slug}/similar":{"get":{"summary":"Similar suppliers","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10}},{"name":"lang","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of similar suppliers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierList"}}}}}}},"/suppliers/compare":{"post":{"summary":"Compare 2-4 suppliers side by side (read-only, no key)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slugs"],"properties":{"slugs":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":4},"lang":{"type":"string"}}}}}},"responses":{"200":{"description":"Side-by-side comparison with shared-signal rollups"}}}},"/suppliers/{slug}/red-flags":{"get":{"summary":"Structured due-diligence signals (partner/enterprise key required)","security":[{"bearerAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Structural signals + data completeness + disclaimer"},"403":{"description":"Key tier does not allow action tools"},"404":{"description":"Supplier not found"}}}},"/suppliers/{slug}/draft-rfq":{"post":{"summary":"Draft an RFQ email grounded in supplier facts (partner/enterprise key required)","security":[{"bearerAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["brief"],"properties":{"brief":{"type":"string","minLength":8,"maxLength":2000},"buyerCompany":{"type":"string"},"quantity":{"type":"string"}}}}}},"responses":{"200":{"description":"RFQ draft text (nothing is sent)"},"403":{"description":"Key tier does not allow action tools"}}}},"/suppliers/{slug}/request-introduction":{"post":{"summary":"Request a supplier introduction (partner/enterprise key required)","security":[{"bearerAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["buyerEmail","briefSnippet"],"properties":{"buyerEmail":{"type":"string","format":"email"},"briefSnippet":{"type":"string","minLength":8,"maxLength":2000},"buyerName":{"type":"string"},"buyerCompany":{"type":"string"}}}}}},"responses":{"200":{"description":"Lead created + routing decision (supplier_direct | managed_sourcing)"},"403":{"description":"Key tier does not allow action tools"}}}},"/suppliers/deep-research":{"post":{"summary":"Deep research: shortlist + dossiers + comparison + next step (partner/enterprise key required)","description":"Non-streaming equivalent of the /mcp/deep SSE endpoint and the find_and_brief MCP tool. Cached 24h on identical brief + filters.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchRequest"}}}},"responses":{"200":{"description":"Full deep-research result (shortlist, dossiers, comparison, nextStep, costUsd, cached)"},"403":{"description":"Key tier does not allow action tools"},"413":{"description":"Payload too large to synthesize within the per-request cost cap"}}}},"/listing-requests":{"post":{"summary":"Request a supplier listing (for agents acting on behalf of a supplier; no key needed)","description":"Submits a \"Request to be added\" for a supplier that is not on Reevol Source yet. A 6-digit code is emailed to `email` (valid 15 minutes); verify it with POST /listing-requests/{requestId}/verify. A company email is best; an AI-agent mailbox (e.g. *@mail.grokbot.com, *@agentmail.to) is fine when `website` is the company's own. Free webmail is rejected. Every request is reviewed before the page goes live (an automated check of the website and products, and a person when needed); the email then gets a \"you are live\" message with the page link. The supplier manages the profile in Reevi (https://compass.reevol.com). Mirrors the request_supplier_listing MCP tool.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingRequest"}}}},"responses":{"200":{"description":"`next`: verify_code (with requestId), already_listed (with supplier + url) or already_requested. `message` says what to do next.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingReply"}}}},"400":{"description":"missing_fields | invalid_website | invalid_email | free_email_not_allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingReply"}}}},"429":{"description":"rate_limited (per IP per hour, per email per day)"}}}},"/listing-requests/{requestId}/verify":{"post":{"summary":"Verify the emailed 6-digit code; the request enters review (automated check, a person when needed)","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","pattern":"^\\d{6}$"}}}}}},"responses":{"200":{"description":"{ ok: true, message }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingReply"}}}},"400":{"description":"invalid_or_expired | too_many_attempts | no_mx"},"404":{"description":"not_found (no request awaiting verification)"}}}},"/listing-requests/{requestId}/resend":{"post":{"summary":"Email a fresh verification code","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ ok: true, message }"},"404":{"description":"not_found"},"429":{"description":"rate_limited"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Agent key: Authorization: Bearer rsk_pub_... Mint at /for-agents/dashboard/. Action tools require partner/enterprise tier."}},"schemas":{"ListingRequest":{"type":"object","required":["companyName","website","email"],"properties":{"companyName":{"type":"string","minLength":2,"maxLength":200},"website":{"type":"string","maxLength":500,"description":"The company's own website."},"email":{"type":"string","format":"email","description":"Where the 6-digit code is sent. Company email or an AI-agent mailbox; no free webmail."},"country":{"type":"string"},"mainProducts":{"type":"string","maxLength":1000},"hsCodes":{"oneOf":[{"type":"array","items":{"type":"string"},"maxItems":10},{"type":"string"}]},"contactName":{"type":"string"},"note":{"type":"string","maxLength":2000},"locale":{"type":"string","description":"Language of the emails to the supplier (en, zh-CN, zh-Hant, ja, ko, vi, th, id, es, pt-BR, fr, de, ar). Default en."}}},"ListingReply":{"type":"object","properties":{"requestId":{"type":"string"},"next":{"type":"string","enum":["verify_code","already_listed","already_requested"]},"ok":{"type":"boolean"},"supplier":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"}}},"url":{"type":"string","format":"uri"},"error":{"type":"string"},"message":{"type":"string","description":"The next step in plain English."}}},"MatchRequest":{"type":"object","required":["brief"],"properties":{"brief":{"type":"string","minLength":8,"maxLength":2000,"description":"Freeform description of what the buyer is sourcing."},"country":{"type":"string","description":"Single canonical country name."},"countries":{"type":"array","items":{"type":"string"},"description":"Multi-country allow-list."},"excludeCountries":{"type":"array","items":{"type":"string"}},"hsCodes":{"type":"array","items":{"type":"string"}},"industry":{"type":"string"},"certifications":{"type":"array","items":{"type":"string"}},"employeeRange":{"type":"array","items":{"type":"string"}},"foundedAfter":{"type":"integer"},"foundedBefore":{"type":"integer"},"businessType":{"type":"string","enum":["manufacturer","trading_company","any"]},"exportMarkets":{"type":"array","items":{"type":"string"}},"limit":{"type":"integer","minimum":1,"maximum":25,"default":10},"lang":{"type":"string"}}},"MatchResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/MatchedSupplier"}},"debug":{"type":"object","properties":{"semanticHits":{"type":"integer"},"filterHits":{"type":"integer"},"embeddingLatencyMs":{"type":"integer"},"searchLatencyMs":{"type":"integer"},"totalLatencyMs":{"type":"integer"}}}}},"MatchedSupplier":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"legalNameEn":{"type":"string"},"legalNameZh":{"type":["string","null"]},"hqCity":{"type":["string","null"]},"hqCountry":{"type":"string"},"industryPrimary":{"type":"string"},"hsCodes":{"type":"array","items":{"type":"string"}},"visibilityScore":{"type":"number"},"semanticScore":{"type":"number","description":"Cosine similarity, 0..1."},"finalScore":{"type":"number","description":"0.7 * semantic + 0.3 * normalized_visibility."},"matchExplanation":{"type":"string","description":"Plain-English reason the supplier surfaced."},"url":{"type":"string","format":"uri"}}},"SupplierList":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SupplierCard"}}}},"SupplierCard":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"legalNameEn":{"type":"string"},"legalNameZh":{"type":["string","null"]},"hqCity":{"type":["string","null"]},"hqCountry":{"type":"string"},"industryPrimary":{"type":"string"},"hsCodes":{"type":"array","items":{"type":"string"}},"visibilityScore":{"type":"number"},"url":{"type":"string","format":"uri"}}},"SupplierProfile":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"legalNameEn":{"type":"string"},"legalNameZh":{"type":["string","null"]},"aliases":{"type":"array","items":{"type":"string"}},"businessType":{"type":["string","null"]},"hqCountry":{"type":"string"},"hqRegion":{"type":["string","null"]},"hqCity":{"type":["string","null"]},"yearFounded":{"type":["integer","null"]},"employeeRange":{"type":["string","null"]},"industryPrimary":{"type":"string"},"industrySub":{"type":"array","items":{"type":"string"}},"hsCodes":{"type":"array","items":{"type":"string"}},"certifications":{"type":"array"},"exportMarkets":{"type":"array","items":{"type":"string"}},"tradeFairs":{"type":"array"},"visibilityScore":{"type":"number"},"websitePublic":{"type":["string","null"]},"linkedinPublic":{"type":["string","null"]},"atlasUpdatedAt":{"type":"string","format":"date-time"},"url":{"type":"string","format":"uri"},"summary":{"type":["string","null"]},"faq":{"type":["array","null"]},"contentLang":{"type":["string","null"]}}}}}}