REST API and API keys

Create a key

1. Go to Settings → Manage API keys.
2. Give the key a name, choose Read only or Read + write, and choose when it expires (30 days, 90 days, 1 year, or never).
3. Click Create key and copy it right away. It’s only shown once.

Each person can have up to 10 active keys per workspace. Viewers can only create read-only keys. Revoke a key from the same page and it stops working immediately. Owners and admins can revoke anyone’s key.

Using a key

Send the key in an Authorization header: “Authorization: Bearer <your key>”. A key acts as the person who created it. If they leave the workspace or are disabled, the key stops working, and if they become a viewer, write requests are refused.

Requests go to https://www.numanknows.com/api/v1. Errors come back as JSON with an error code and message.

For examples and the full reference, see the developer docs. The machine-readable OpenAPI spec is at https://www.numanknows.com/api/v1/openapi.json.

Endpoints

• GET /me: the key’s workspace, your role, and the key’s details. A quick way to check a key works.
• GET /listings and GET /listings/{id}: search the catalog by criteria, and read one listing’s facts and summary. Each listing says whether it’s available, under contract, sold or withdrawn, or not checked recently. Search leaves out sold or withdrawn listings unless you add include_unavailable=true.
• GET /pipeline, GET /pipeline/{id}: your tracked deals. POST /pipeline tracks a listing as a deal, and PATCH /pipeline/{id} updates one (needs Read + write).
• GET /search-profiles and GET /search-profiles/{id}: your saved searches. POST, PATCH, and DELETE manage them (needs Read + write).
• POST /calculator: the SBA 7(a) loan math behind the buy signal, for a price and SDE you supply. Its year_one_owner_cash is SDE minus debt service, your salary included (since 2026-10-14 it no longer adds owner_salary on top, which counted it twice).

Lists return 25 results by default (up to 50) with limit and offset parameters. None of these endpoints use AI credits.

Rate limits

Each key can make up to 60 requests a minute and 1,000 an hour. Over the limit, you get a 429 response with a Retry-After header saying how many seconds to wait.