Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.keplerinsights.us/llms.txt

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

​
1. Get an API key

Sign in at api.keplerinsights.us (magic-link email or passkey), then create a key. You’ll get one live key (ki_live_…) and access to test keys (ki_test_…) for sandbox development. The raw key is shown once at creation. Save it in your secrets manager — Kepler stores only a hash and cannot recover it.

​
2. Make your first call (sandbox)

curl https://api.keplerinsights.us/v1/score \
  -H "X-API-Key: ki_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "acme.test"}'
Response: 
{
  "mode": "sandbox",
  "domain": "acme.test",
  "scored_at": "2026-05-12T18:30:00Z",
  "ki_rating": "KI-1",
  "composite_score": 67.2,
  "scale_premium": 4.1,
  "buckets": {
    "team_structure": 68.0,
    "market_position": 71.5,
    "momentum_tailwinds": 64.3,
    "financial_health": 61.0
  },
  "rank": { "percentile": 92, "cohort_size": 540 }
}
The mode: sandbox field tells you this is canned data. See Sandbox for the four test domains and what each one represents.

​
3. Score a real company

Swap your key prefix to ki_live_ and use a real domain: 
curl https://api.keplerinsights.us/v1/score \
  -H "X-API-Key: ki_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "stripe.com"}'
If Kepler has a recent record (within your tier’s freshness window — 24h on Starter, 6h on Growth, 1h on Scale), you get it back instantly as a 200 with x_kepler.cache_status: "cached". Otherwise the server returns 202 Accepted with a job_id — poll GET /v1/jobs/{job_id} until status: complete, then fetch the result with GET /v1/score/{domain}. See Async scoring for the full polling pattern.
The official SDKs hide the polling for you — Kepler#score() blocks transparently across both response shapes. Branch on shape only if you’re calling the API directly: response body has composite_score → score inline, has job_id → poll.

​
4. Read the history

curl "https://api.keplerinsights.us/v1/score/stripe.com/history?limit=10" \
  -H "X-API-Key: ki_live_YOUR_KEY"
Returns the 10 most recent scoring runs as a time-series. Use the next_cursor field for pagination.

Authentication

Key prefixes, rotation, security model.

Sandbox

The 4 canned test domains.

Tiers

Quotas, freshness windows, async eligibility.

Errors

Every code we return + how to recover.