Skip to main content

Documentation Index

Fetch the complete documentation index at: https://keplerinsights.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

The sandbox lets you build and test against real-shape responses without burning fetcher credits. Every paid tier and the Free trial includes test keys; you can hold as many as you want.

​
Activating sandbox mode

Use a key prefixed ki_test_. There’s no separate base URL or stage — the same endpoints handle both modes, and the active mode is determined by the key prefix. 
curl https://api.keplerinsights.us/v1/score \
  -H "X-API-Key: ki_test_YOUR_KEY" \
  -d '{"domain": "acme.test"}'
Every sandbox response carries a top-level mode: "sandbox" field so your code can detect canned data unambiguously. Live responses do not carry this field; its absence means “this is real data.” 
{
  "mode": "sandbox",
  "domain": "acme.test",
  "composite_score": 67.2,
  ...
}
(Exception: GET /v1/signals returns identical content in both modes — the schema manifest is deterministic — and is not tagged.)

​
The four canned domains

DomainKI RatingCompositeUse it for
acme.testKI-167.2Healthy baseline — strong-but-not-top result. Good default for screenshots.
unicorn.testKI-1+79.4Elite outlier. Has a large scale premium (7.8). Use to test top-of-rank rendering.
struggling.testKI-432.1Distressed company. Confidence band returns directional with missing fetcher data. Use to test low-confidence + warning UI.
cohort.testKI-345.0Mid-pack. The cohort response uses this as the target so members spread realistically above and below.

​
What the sandbox covers

Every endpoint accepts ki_test_ keys. Coverage parity is verified by an automated test suite — if the live API supports it, the sandbox returns shape-equivalent canned data for it.
EndpointSandbox behavior
POST /v1/score, GET /v1/score/{domain}Canned score for the 4 test domains. Live keys reject them.
POST /v1/score?wait=falseReturns a real job_id writing to the jobs table; status flips pending → complete after a 5-second age threshold so you can exercise the full poll loop.
GET /v1/jobs/{job_id}Reads the sandbox job row. Settles age-based instead of via a real execution.
GET /v1/score/{domain}/history4–12 deterministic records ending now, going back daily. Pagination + cursor work identically to live.
GET /v1/company/{domain}/cohort12 synthetic members named cohort-NN.test, spread around the target.
GET /v1/company/{domain}/confidencePer-domain canned band + completeness + missing-signal list.
GET /v1/distribution12-domain mini-universe with realistic histograms + rating mix + profile split.
GET /v1/moversCanned top-5 gainers + decliners across all windows (sandbox doesn’t differentiate by window).
GET /v1/signalsIdentical to live — the 67-signal manifest is deterministic.
GET /v1/usagePer-tier canned counters at a healthy mid-month position.

​
Rejection rules

  • Test domain on a live key → 400 { "error": "test domains require a ki_test_ key" }
  • Real domain on a test key → 400 { "error": "sandbox: only ['acme.test', 'cohort.test', 'struggling.test', 'unicorn.test'] supported" }
  • Async cold scoring (wait=false) is gated to Growth+ — using a test key on Free/Starter still triggers the tier check.

​
When to graduate

When your integration is rendering canned data correctly across every shape you care about, swap your key prefix to ki_live_ and run the same call against a real domain. The shapes are identical (minus the mode field). The first real call typically costs us 30–60 seconds of cold-scoring time and a few dollars of fetcher spend — be intentional about which company you score first.