Developers

API guide

Start checks of your verified websites and read the results from your own systems. Create a key on the API keys page.

How do I use my key?

Send it in the Authorization header. A key acts for your account: it sees the websites in My websites, and starts checks only of the ones you have verified. We look for your ownership proof again before every check, just like on the website.

curl https://www.kiplock.com/api/v1/sites \
  -H "Authorization: Bearer kl_live_YOUR_KEY"

Which requests can I make?

GET /sites: Your saved websites, with whether each is verified and its latest check.
POST /sites/:id/checks: Starts a check of a verified website. Answers with the check's id.
GET /sites/:id/checks: The website's 20 most recent checks.
GET /checks/:id: One check: its status, score, grade and every finding with how to fix it.

How do I run a check and get the result?

Start a check, then ask for it every few seconds until its status is "complete".

# Start a check
curl -X POST https://www.kiplock.com/api/v1/sites/SITE_ID/checks \
  -H "Authorization: Bearer kl_live_YOUR_KEY"
# → {"id":"CHECK_ID","status":"queued","reused":false}

# Ask every few seconds until "status" is "complete"
curl https://www.kiplock.com/api/v1/checks/CHECK_ID \
  -H "Authorization: Bearer kl_live_YOUR_KEY"

What are the limits?

Up to 300 requests and 20 new checks per key per hour. A check started within 2 minutes of the last one returns that one ("reused": true).

What do errors look like?

Errors come back as JSON with a code: unauthorized (missing or revoked key), ownership_required (verify the site again), rate_limited (wait and retry) or not_found.

What if a key leaks?

Revoke it on the API keys page straight away and create a new one. Keep keys out of code you share and out of web pages.