Developers

There are two ways to connect your own tools to numanknows. Use the MCP connector to work with your deals from an AI assistant or code editor. Use the REST API to build your own scripts and integrations.

MCP connector (Claude, ChatGPT, VS Code, Cursor)

The connector lives at https://www.numanknows.com/api/mcp. There's no key to copy: the first time you use it, your assistant opens a browser window where you sign in to numanknows and approve access. It then acts as you, with your role, and sees only your organization's deals. It has the same tools as the REST API below:

• search_listings: Search the catalog by price, SDE, multiple, sector and place
• get_listing: One listing's facts, availability and your AI scores
• get_comparables: Comparable analysis: market comps and your own past deals
• research_listing: Extract facts from a listing page your assistant read
• upload_listing: Add those facts to your watchlist
• get_watchlist: Listings your organization follows
• calculate_deal: SBA 7(a) deal math
• get_pipeline: Your tracked deals
• add_to_pipeline: Track a listing as a deal, with a note
• update_pipeline_entry: Move a deal's stage, rename it, or add a note
• upload_document: Attach a CIM, P&L or contract to a deal
• get_search_profiles: Your saved searches
• draft_outreach_letter: Draft an off-market letter to an owner, for you to send
• get_outreach_drafts: A deal's saved outreach drafts
• chat_about_deal: Ask numan about a deal (same thread as the app)
• list_diligence_items: A deal's diligence checklist, plus tools to update it
• search: Keyword search of the catalog, in the shape ChatGPT deep research expects
• fetch: One catalog listing as citable text, for the same ChatGPT features

What you're approving: an app you connect this way gets full access to your numanknows account, including your deals, documents and relayed email, and can act on your behalf. Its access isn't limited to the tools listed here. The app's name on the approval screen is supplied by the app itself and isn't verified by numanknows, so only approve apps you trust and check the address it sends you back to.

To disconnect an app, revoke it in Settings, Connected apps. It can't get new access after that, but an access token it already holds keeps working until it expires, within an hour.

Tools that use AI (research_listing, draft_outreach_letter, chat_about_deal) count toward your organization's usage the same way they do in the app. Outreach drafts are never sent: you review, edit and send them yourself.

Claude Code

claude mcp add --transport http numanknows https://www.numanknows.com/api/mcp

VS Code (GitHub Copilot agent mode): add this to .vscode/mcp.json in your workspace, or run MCP: Add Server from the command palette.

{
  "servers": {
    "numanknows": { "type": "http", "url": "https://www.numanknows.com/api/mcp" }
  }
}

Cursor: add this to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).

{
  "mcpServers": {
    "numanknows": { "url": "https://www.numanknows.com/api/mcp" }
  }
}

OpenAI Codex (CLI, IDE extension and desktop app): add this to ~/.codex/config.toml, then run codex mcp login numanknows.

[mcp_servers.numanknows]
url = "https://www.numanknows.com/api/mcp"

Claude.ai and ChatGPT: add a custom connector and paste https://www.numanknows.com/api/mcp as its URL. In ChatGPT this is under Plugins (add a custom MCP server), which needs developer mode; on Business and Enterprise workspaces an admin may have to allow it. ChatGPT deep research and company knowledge use the read-only search and fetch tools. They cover the shared listing catalog only, never your pipeline, documents or off-market entries, and cite each listing's numanknows page.

REST API

Base URL: https://www.numanknows.com/api/v1. The full contract is published as an OpenAPI 3.1 document at https://www.numanknows.com/api/v1/openapi.json, which you can load into Postman, Insomnia or a client generator.

Authentication

• Create a key in Settings, API keys. You'll see it once, so store it somewhere safe.
• Send it on every request as Authorization: Bearer nk_live_…. The X-API-Key header also works.
• A key belongs to one organization. It acts as the teammate who created it, with whatever role they have now. If they leave the organization, their keys stop working.
• Read keys can call every GET endpoint and the calculator. Read + write keys can also create and change deals, documents, the watchlist and saved searches, and call the AI endpoints, as long as their teammate is an owner, admin or member. Viewers can only create read keys.
• Keys expire after 30 days, 90 days (the default) or a year. Owners and admins can also create a key that never expires, though rotating keys is safer. You'll get a reminder about a week before a key expires, and you can revoke one at any time. An expired key gets a 401 with the code api_key_expired.

curl https://www.numanknows.com/api/v1/me \
  -H "Authorization: Bearer $NUMANKNOWS_API_KEY"

Endpoints

Examples

Find HVAC businesses in Texas under $2M:

curl "https://www.numanknows.com/api/v1/listings?q=hvac&geography=texas&max_price=2000000" \
  -H "Authorization: Bearer $NUMANKNOWS_API_KEY"

Track one as a deal, then move it forward:

curl -X POST https://www.numanknows.com/api/v1/pipeline \
  -H "Authorization: Bearer $NUMANKNOWS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_id": "LISTING_ID"}'

curl -X PATCH https://www.numanknows.com/api/v1/pipeline/DEAL_ID \
  -H "Authorization: Bearer $NUMANKNOWS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "Contacted", "last_contact_date": "2026-10-12"}'

Check whether a deal pencils out with 10% down at 10.5% over 10 years:

curl -X POST https://www.numanknows.com/api/v1/calculator \
  -H "Authorization: Bearer $NUMANKNOWS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"price": 1200000, "sde": 380000, "equity_pct": 10, "rate": 10.5, "term": 10}'

Listing data

Listings come back as facts: asking price, SDE, EBITDA, revenue, multiple, geography and sector, plus a short description that numanknows writes itself. The API never returns photos or the seller's own wording, and it only includes listings from sources whose terms allow it, so it can return fewer listings than you see in the app. Each listing links to its source page, which is where you contact the seller or broker.

Each listing also has an availability_status: available, under_contract, sold_or_withdrawn or unknown (not checked recently), with availability_checked_at saying when we last looked. Search leaves out sold or withdrawn listings unless you add include_unavailable=true. Under-contract listings stay in, since a deal can fall through. Fetching a listing by its ID always works, even after it sells.

Pagination, limits and errors

• List endpoints take limit (up to 50) and offset (up to 500), and return pagination.has_more.
• Each key can make 60 requests per minute and 1,000 requests per hour. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit you'll get a 429 with a Retry-After header.
• Errors look like {"error": {"code": "not_found", "message": "…"}}. The code stays stable, so branch on it rather than on the message.
• Owners and admins can see every change made through the API, and every read of deals and saved searches, under Settings, API keys.

Changes

• 2026-10-15: Added comparables, the watchlist, listing research, document upload and off-market outreach drafts, and an optional note on POST /pipeline and PATCH /pipeline/{id}. The MCP connector gained the same tools.
• 2026-10-14: POST /calculator now returns year_one_owner_cash as SDE minus debt service. SDE already includes the owner's pay, so it no longer adds owner_salary on top, which had counted the salary twice. The field name is unchanged.