{"openapi":"3.1.0","info":{"title":"NewHands API","version":"2026-10-19","summary":"Versioned REST API for an agent-ready SMB marketplace.","description":"Search New England business listings, match buyer criteria, and take deal-stage actions on behalf of a verified principal. Listing documents follow newhands.smb-listing 1.0.0. Binding actions (NDA signature, LOI) requested by an agent return pending_human_approval instead of executing. Every seeded listing is a fictional sample."},"servers":[{"url":"https://getnewhands.com"}],"tags":[{"name":"Listings"},{"name":"Matching"},{"name":"Deals"},{"name":"Events"},{"name":"Index"},{"name":"Resources"}],"components":{"securitySchemes":{"agentKey":{"type":"http","scheme":"bearer","description":"Agent key delegated by a verified human principal. Sample keys are published only for local development."},"session":{"type":"apiKey","in":"cookie","name":"authjs.session-token","description":"Human session from the email magic-link sign-in."}}},"paths":{"/api/v1/listings":{"get":{"tags":["Listings"],"summary":"Search listings","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"state","in":"query","schema":{"type":"string","description":"Any USPS abbreviation. Omit it to search the country."}},{"name":"scope","in":"query","schema":{"type":"string","enum":["all","new_england","outside"],"default":"all","description":"The website defaults to New England. The API defaults to all US states."}},{"name":"industry","in":"query","schema":{"type":"string"}},{"name":"town","in":"query","schema":{"type":"string"}},{"name":"priceMin","in":"query","schema":{"type":"integer"}},{"name":"priceMax","in":"query","schema":{"type":"integer"}},{"name":"sba","in":"query","schema":{"type":"boolean"}},{"name":"sellerFinancing","in":"query","schema":{"type":"boolean"}},{"name":"turnkeyReady","in":"query","schema":{"type":"boolean","description":"When true, only listings whose Turnkey Ready badge is certified: verified financials, a clean diligence file, and a transition plan."}},{"name":"realEstate","in":"query","schema":{"type":"string","enum":["included","leased","none"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["newest","price_asc","price_desc","sde_desc"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":24}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Listing page. Confidential fields are omitted."}}}},"/api/v1/listings/{slug}":{"get":{"tags":["Listings"],"summary":"Listing detail","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SMB listing document. confidential is present only after a signed NDA for the caller."}}}},"/api/v1/match":{"post":{"tags":["Matching"],"summary":"Match buyer criteria to active listings","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"buyerId":{"type":"string"},"criteria":{"type":"object"}}}}}},"responses":{"200":{"description":"Explainable scores, highest first."}}}},"/api/v1/deals/{id}":{"get":{"tags":["Deals"],"summary":"Deal room","security":[{"agentKey":[]},{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Diligence, Q&A, indications, and stage."}}}},"/api/v1/deals/{id}/actions":{"post":{"tags":["Deals"],"summary":"Deal-stage action","security":[{"agentKey":[]},{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["nda.sign","ioi.submit","loi.submit","qa.ask","qa.answer","documents.request","documents.update","deal.advance"]},"listingSlug":{"type":"string"},"signedName":{"type":"string"},"price":{"type":"integer"},"structure":{"type":"string"},"financing":{"type":"string"},"timeline":{"type":"string"},"narrative":{"type":"string"},"question":{"type":"string"},"answer":{"type":"string"},"threadId":{"type":"string"},"documentName":{"type":"string"},"stage":{"type":"string"}}}}}},"responses":{"200":{"description":"Completed, or pending_human_approval for binding agent actions."}}}},"/api/v1/events":{"get":{"tags":["Events"],"summary":"Event feed","parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Recent listing and deal-stage events."}}}},"/api/v1/webhooks":{"post":{"tags":["Events"],"summary":"Register a webhook","security":[{"session":[]},{"agentKey":[]}],"responses":{"201":{"description":"Subscription created. Deliveries are signed with X-NewHands-Signature."}}}},"/api/v1/index":{"get":{"tags":["Index"],"summary":"Search the cross-source index","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"state","in":"query","schema":{"type":"string","description":"Any USPS abbreviation."}},{"name":"scope","in":"query","schema":{"type":"string","enum":["all","new_england","outside"],"description":"Defaults to all. new_england matches the website's opening view."}},{"name":"set","in":"query","schema":{"type":"string","enum":["for_sale","licenses","public","all"]}},{"name":"signal","in":"query","schema":{"type":"string"}},{"name":"source","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Normalized index rows with attribution. Sample rows are marked. Non-sale records say so."}}}},"/api/v1/markets":{"get":{"tags":["Index"],"summary":"Market stats from the index","responses":{"200":{"description":"Median ask, multiple, and counts for active for-sale rows. Sample share is included."}}}},"/api/v1/calculators":{"get":{"tags":["Resources"],"summary":"List versioned calculators","responses":{"200":{"description":"Names, version, and vector counts. Educational."}}}},"/api/v1/calculators/{name}":{"get":{"tags":["Resources"],"summary":"Calculator description and published test vectors","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Vectors an agent can use to verify outputs."}}},"post":{"tags":["Resources"],"summary":"Run a calculator","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Result plus calculator version."}}}},"/api/v1/markets/report":{"get":{"tags":["Index"],"summary":"New England Main Street Market Report","responses":{"200":{"description":"Index figures for New England, with sample counts. Not a census."}}}},"/api/v1/resources":{"get":{"tags":["Resources"],"summary":"List educational resources","responses":{"200":{"description":"Buyer, seller, broker, and shared guides. Not advice."}}}},"/api/v1/resources/{slug}":{"get":{"tags":["Resources"],"summary":"One resource as JSON, or markdown with ?format=md","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Markdown body plus citations."}}}},"/api/v1/feeds":{"post":{"tags":["Index"],"summary":"Broker partner feed upload","security":[{"session":[]},{"agentKey":[]}],"responses":{"201":{"description":"Rows upserted. Sample unless rights are attested."}}}},"/api/mcp":{"post":{"tags":["Deals"],"summary":"MCP JSON-RPC endpoint","description":"Tools: search_listings, get_listing, match_listings, request_nda, submit_indication, ask_question, get_deal, list_events, search_index, market_stats, list_resources, get_resource, list_calculators, run_calculator.","responses":{"200":{"description":"JSON-RPC 2.0 result."}}}}}}