API Overview

KEPCA exposes two integration surfaces:

1. Client-side Widget — a <maptcha-widget> custom element that handles the full challenge flow in the browser.
2. REST API — server-side endpoints for token verification, event reporting, site management, and analytics.

Architecture

Browser (Widget)                 KEPCA API                    Your Backend
 ├─ /v1/{sk}/init         ────>  Challenge Service      <──── /v1/siteverify
 ├─ /v1/{sk}/challenge    ────>                         <──── /v1/events
 └─ /v1/{sk}/solve        ────>                         <──── /v1/stats/{sk}
                                                        <──── /v1/sites
                                                        <──── /v1/auth/*

Client-side (Widget)

The widget communicates with three endpoints to run the challenge flow:

Endpoint	Purpose
POST /v1/{site_key}/init	Start session, submit signals
POST /v1/{site_key}/challenge	Request a challenge
POST /v1/{site_key}/solve	Submit challenge solution

These calls are made automatically by the widget. You do not need to call them yourself.

Server-side (REST)

Your backend uses these endpoints after form submission:

Endpoint	Purpose
POST /v1/siteverify	Verify a captcha token
POST /v1/events	Report custom events
GET /v1/stats/{site_key}	Retrieve analytics

Admin

Site, account, and team management:

Endpoint	Purpose
POST /v1/auth/register	Create account
POST /v1/auth/login	Authenticate
POST /v1/sites	Create / manage sites
POST /v1/teams	Create / manage teams
POST /v1/domains	Custom domain management
POST /v1/webhooks	Webhook management
POST /v1/keys/rotate	API key rotation
GET /v1/billing/plan	Billing plan and usage
GET /v1/audit	Audit log
GET /health	Health check
GET /metrics	Prometheus metrics

Authentication

Server-side endpoints require your secret key in the request body (secret field) or as a Bearer token in the Authorization header.

Admin endpoints use JWT tokens obtained from /v1/auth/login.

Base URL

Environment	URL
Production	https://api.kepca.com
Self-hosted	Your configured domain
Local dev	http://localhost:3001

Next steps

• Widget API — attributes, events, and CSS custom properties
• REST API — full endpoint reference with request/response examples