Keys
An admin makes a key in Settings, Workspace, API keys. It is shown once. Kaypo keeps only a hash of it, so a lost key is revoked and replaced rather than recovered. Send it on every request as Authorization: Bearer kpo_... or as X-Api-Key.
A key reads as the admin who made it, which is the whole workspace. If that person stops being an admin, or leaves, the key stops working and an admin makes a new one.
Limits and the log
600 requests an hour for each key, across every endpoint. Each request is written down with the endpoint, what was asked, how many things came back and how it went. What came back is never kept.
Answers carry no email addresses, no email or call text and no scoring weights. A score comes with its explanation, and the weights behind it stay inside Kaypo.
Scores
GET /api/v1/scores
Every scored open deal, highest first, with the reasons behind the number and what is holding it back. Built for a warehouse: page through it with limit and offset.
| Parameter | In | Type | What it does |
|---|---|---|---|
limit | query | integer, 1 to 500 | How many deals in one page. Default 100. |
offset | query | integer | Where the page starts. Default 0. |
min_score | query | number | Leave out deals scored below this. |
Returns total | limit | offset | deals[]: id, deal_name, account_name, account_domain, amount_cents, stage, close_date, score, previous_score, movement, scored_at, reasons, holding_back, engagement_score, company_fit, company_fit_reasons
curl -H "Authorization: Bearer $KAYPO_KEY" "https://kaypo.io/api/v1/scores?min_score=60"
Deals
GET /api/v1/deals
Open deals with their score, the change since the last nightly run and a one sentence reason, in the same views as the Deals page: what moved most, what is dropping, what is rising, and the highest scores.
| Parameter | In | Type | What it does |
|---|---|---|---|
view | query | moved_today | dropping | rising | all | Which deals, in which order. Default moved_today. |
limit | query | integer, 1 to 50 | How many deals. Default 15. |
owner | query | text | Only deals whose owner name contains this. |
Returns view | note | count | deals[]: id, name, company, amount, stage, owner, score, change, reason, link
curl -H "Authorization: Bearer $KAYPO_KEY" "https://kaypo.io/api/v1/deals?view=dropping&limit=10" $ kaypo deals --view dropping
Explain a deal
GET /api/v1/deals/{id}/explain
Why one deal scores what it does: a starting point and every signal with its points, adding up to the score, what changed since the last run, and the fields the rep entered in the CRM, kept apart from what the buyer did. An open deal adds its chance of closing this quarter and of winning at all. The id can also be the deal or company name. When several match, the answer is a 404 with the candidates.
| Parameter | In | Type | What it does |
|---|---|---|---|
id | path | deal id or name | The deal. |
Returns found | deal | buyer_evidence: starting_point, contributions[], recent_signals[] | since_last_run | rep_entered | forecast | candidates[] (when several match)
curl -H "Authorization: Bearer $KAYPO_KEY" "https://kaypo.io/api/v1/deals/Fairholm%20Solutions/explain" $ kaypo explain "Fairholm Solutions"
Discover
GET /api/v1/discover
Companies outside your CRM that look like your wins, from Sourcing. Fit is the share of your own closed deals like the company that you won, and it always comes with both counts, so 70 means you won at least 7 of every 10 like it. A company listed for another reason, such as a past buyer joining it, has no fit, and min_fit leaves it out.
| Parameter | In | Type | What it does |
|---|---|---|---|
min_fit | query | number, 0 to 100 | Only companies with at least this fit. |
limit | query | integer, 1 to 500 | How many companies. Default 50. |
format | query | json | csv | csv answers with a spreadsheet. Accept: text/csv does the same. Default json. |
Returns total | min_fit | note | companies[]: company, domain, about, fit, fit_won, fit_closed, fit_basis, why_now, next_step, contact, kaypo_link
curl -H "Authorization: Bearer $KAYPO_KEY" "https://kaypo.io/api/v1/discover?min_fit=70&format=csv" $ kaypo discover --min-fit 70 --csv > firms.csv
Past champions who moved
GET /api/v1/champions
Senior people from deals you won who have since changed jobs: where they were, the deal you won with them, and where they work now. Newest move first.
| Parameter | In | Type | What it does |
|---|---|---|---|
limit | query | integer, 1 to 100 | How many people. Default 25. |
Returns champions[]: name, was, was_at, won_with_them, won_on, now_at, now_domain, now_title, moved | message (when there are none)
curl -H "Authorization: Bearer $KAYPO_KEY" "https://kaypo.io/api/v1/champions" $ kaypo champions
Research an account
GET /api/v1/accounts/{domain}/research
A brief on one company in your CRM before a call: what it is, its family from the CRM's own parent and child links, its open deals, what happened there in the last 60 days, past champions who now work there, and its hiring: postings from the last 60 days and whether one looks the way your wins posted before they closed. A company that is not in the workspace is a 404.
| Parameter | In | Type | What it does |
|---|---|---|---|
domain | path | domain | The company's web domain, for example fairholm.com. |
Returns found | company | family[] | open_deals[] | recent_activity[] | past_champions_here[] | hiring: postings_last_60_days[], like_your_wins | candidates[] (when several match)
curl -H "Authorization: Bearer $KAYPO_KEY" "https://kaypo.io/api/v1/accounts/fairholm.com/research" $ kaypo research fairholm.com
What you sell
GET /api/v1/knowledge
Your own description of what you sell, who it is for, the problems it solves, the proof you may use and the words you never use, from Settings, Knowledge. Read it before writing anything on your behalf.
Returns filled | what_we_sell | who_it_is_for | problems_we_solve | proof_we_can_use | words_we_never_use | updated_at | link
curl -H "Authorization: Bearer $KAYPO_KEY" "https://kaypo.io/api/v1/knowledge" $ kaypo knowledge
Hiring like your wins
GET /api/v1/hiring
The job posting patterns that came before your wins, each with how many wins and how many losses posted that way in the 90 days before closing, the pattern left out because it shows up as often before losses, and the companies hiring that way now.
| Parameter | In | Type | What it does |
|---|---|---|---|
limit | query | integer | How many companies hiring now, 1 to 25. Default 25. |
Returns based_on | patterns[] | left_out | hiring_now[] | message (when nothing is learned yet)
curl -H "Authorization: Bearer $KAYPO_KEY" "https://kaypo.io/api/v1/hiring" $ kaypo hiring
Company families
GET /api/v1/families
Your company families from the parent company links in your CRM: the parent, how many companies are in each, how many are customers, how many have an open deal, and the ones nobody has a deal with yet. Counts only, no amounts.
| Parameter | In | Type | What it does |
|---|---|---|---|
limit | query | integer | How many families, 1 to 100, most customers first. Default 25. |
Returns total | note | families[] | message (when the CRM records no parent links)
curl -H "Authorization: Bearer $KAYPO_KEY" "https://kaypo.io/api/v1/families" $ kaypo families
Goal status
GET /api/v1/goal
The goal set on the Agents page: what it asks for, meetings booked and to go, days left, the plays Kaypo planned with the proof for each, the Friday check-ins and what waits in the agents queue. goal is null when none is set.
Returns goal | message (when no goal is set)
curl -H "Authorization: Bearer $KAYPO_KEY" "https://kaypo.io/api/v1/goal" $ kaypo goal
Grade the signals you pay for
GET /api/v1/vendor-signals
Every field your tools write into your CRM, and Kaypo's own outside signals, graded against your closed deals as each stood before the deal closed: came before wins, leans toward losses, predicts nothing, or not enough history. Each comes with both counts, an odds ratio with its interval, whether it adds anything beyond Kaypo's score on deals the model never saw, which of Kaypo's own signals already covers a field that adds nothing (overlap), and a reason with a code. Also the cutoff Kaypo chose, each tool's cost beside its grades when an admin entered one, and the fields waiting for review.
| Parameter | In | Type | What it does |
|---|---|---|---|
limit | query | integer | How many fields, 1 to 50, the ones that add to Kaypo's score first. Default 25. |
Returns graded_at | partial (when not every deal was read yet) | based_on | cutoff | summary | fields[] | kaypo_own_signals | costs[] | fields_kaypo_found | message (when nothing is graded yet)
curl -H "Authorization: Bearer $KAYPO_KEY" "https://kaypo.io/api/v1/vendor-signals"
Errors
| Status | When |
|---|---|
| 400 | A parameter is not one of the allowed values. The error says which. |
| 401 | No key, or a key that is not valid or was revoked. |
| 403 | The admin who made the key is no longer an admin, or the workspace is not active. Make a new key. |
| 404 | The deal or company asked for is not in the workspace, or several match (the candidates come back). |
| 429 | More than 600 requests in an hour on one key. Retry-After says when to try again. |
| 500 | Kaypo could not answer. The error carries a short reference to quote. |
Every error is JSON with one field, error, written as a sentence.
The command line
kaypo is a small Node tool with no dependencies. Every command is one of the calls above made with your key, so Claude Code, Codex or a cron job can run it the same way you do. It prints plain tables, or JSON with --json.
It is one file, served from this site at kaypo.io/cli/kaypo.mjs. Download it and run it with Node 18 or later. There is nothing else to install, and it is not on npm.
$ curl -fsSL https://kaypo.io/cli/kaypo.mjs -o ~/kaypo.mjs $ alias kaypo="node ~/kaypo.mjs" # add this line to ~/.zshrc or ~/.bashrc to keep it $ kaypo login # paste the key, kept in ~/.kaypo/config.json and readable only by you $ kaypo deals --view dropping $ kaypo explain "Fairholm Solutions" $ kaypo discover --min-fit 70 --csv > firms.csv $ kaypo champions $ kaypo research fairholm.com $ kaypo hiring $ kaypo families $ kaypo goal $ kaypo knowledge --json
On Windows, save the file from the link above and run node kaypo.mjs login in the folder you saved it to. Download it again to update; kaypo --version says which one you have.
KAYPO_API_KEY in the environment is used instead of the saved key when it is set, and KAYPO_URL points the tool at another address.
From Claude
The same answers are in Claude through the Kaypo connector, signed in as yourself rather than with a key, and limited to the deals you can see in Kaypo.
