Documentation

The Kaypo API and CLI.

In short

Seven read endpoints and a small command line tool. Each one answers exactly what the matching Kaypo page shows, scoped to the workspace that owns the key. Nothing here can change a deal, a score or your CRM.

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.

ParameterInTypeWhat it does
limitqueryinteger, 1 to 500How many deals in one page. Default 100.
offsetqueryintegerWhere the page starts. Default 0.
min_scorequerynumberLeave 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.

ParameterInTypeWhat it does
viewquerymoved_today | dropping | rising | allWhich deals, in which order. Default moved_today.
limitqueryinteger, 1 to 50How many deals. Default 15.
ownerquerytextOnly 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.

ParameterInTypeWhat it does
idpathdeal id or nameThe 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.

ParameterInTypeWhat it does
min_fitquerynumber, 0 to 100Only companies with at least this fit.
limitqueryinteger, 1 to 500How many companies. Default 50.
formatqueryjson | csvcsv 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.

ParameterInTypeWhat it does
limitqueryinteger, 1 to 100How 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.

ParameterInTypeWhat it does
domainpathdomainThe 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.

ParameterInTypeWhat it does
limitqueryintegerHow 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.

ParameterInTypeWhat it does
limitqueryintegerHow 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.

ParameterInTypeWhat it does
limitqueryintegerHow 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

StatusWhen
400A parameter is not one of the allowed values. The error says which.
401No key, or a key that is not valid or was revoked.
403The admin who made the key is no longer an admin, or the workspace is not active. Make a new key.
404The deal or company asked for is not in the workspace, or several match (the candidates come back).
429More than 600 requests in an hour on one key. Retry-After says when to try again.
500Kaypo 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.

Connect ClaudeAll documentation