Human? Read the OpenAPI docs

PINCHA

Reverse CAPTCHA - verify AI agents, not humans.

How It Works

PINCHA presents deterministic challenges (ROT13, regex, checksums, etc.) that are trivial for agents but tedious for humans. Sites integrate PINCHA to verify automated access.

1. Your site requests a challenge from PINCHA
2. Agent sees the challenge and solves it
3. PINCHA returns a signed token
4. Your server validates the token with your secret

Integration Option 1: Widget (Browser-Based)

For agents operating in a browser context (e.g., browser automation, web agents).

Step 1: Create Account

POST http://pincha.bot/api/v1/auth/register
{"email": "you@example.com", "password": "..."}
→ {"api_key": "ak_..."}

Step 2: Register Your Site

POST http://pincha.bot/api/v1/sites/create
Authorization: Bearer ak_...
{"name": "My App", "allowed_origins": ["https://myapp.com"]}
→ {"site_key": "pub_...", "site_secret": "sec_..."}

Save site_secret securely - it's only shown once.

Step 3: Embed Widget

<script src="http://pincha.bot/static/widget.js"></script>
<div id="pincha-container"></div>
<script>
Pincha.init({
  container: '#pincha-container',
  siteKey: 'pub_...',
  onSuccess: function(token) {
    // Send token to your server for validation
    fetch('/verify-agent', {method: 'POST', body: JSON.stringify({token})});
  }
});
</script>

Step 4: Validate Token (Server-Side)

POST http://pincha.bot/api/v1/token/validate
{"token": "pincha_v1_...", "site_secret": "sec_..."}
→ {"valid": true, "session_id": "sess_...", "solved_in_ms": 127}

Widget Flow Diagram

[WIDGET] → [PINCHA] Create session, get shortcode_url
[WIDGET] Renders shortcode, listens on SSE
[AGENT]  Sees shortcode in DOM
[AGENT]  → [PINCHA] GET /b/{shortcode} (Accept: application/json)
[AGENT]  Solves challenge
[AGENT]  → [PINCHA] POST /b/{shortcode} {"solution": "..."}
[PINCHA] → [WIDGET] SSE returns token
[WIDGET] Calls onSuccess(token)
[YOUR SERVER] Validates token with site_secret

Integration Option 2: API (Server-to-Server)

For agents interacting with your API directly (e.g., CLI tools, API clients).

Step 1-2: Same as Above

Create account and register site to get site_key and site_secret.

Step 3: Create Challenge

POST http://pincha.bot/api/v1/session/create
{"site_key": "pub_..."}
→ {
    "session_id": "sess_...",
    "shortcode_url": "http://pincha.bot/b/abc123",
    "challenge": {"prompt": "Decode: uryyb", "instructions": "Apply ROT13 cipher"}
  }

Step 4: Agent Solves and Submits

POST http://pincha.bot/api/v1/session/verify
{"session_id": "sess_...", "solution": "hello"}
→ {"success": true, "token": "pincha_v1_..."}

Step 5: Validate Token

POST http://pincha.bot/api/v1/token/validate
{"token": "pincha_v1_...", "site_secret": "sec_..."}
→ {"valid": true}

Payload Signing (Optional)

Prove that specific data was submitted by an agent. Include a payload with the solution - its hash is signed into the token.

# Agent submits solution with payload
POST http://pincha.bot/api/v1/session/verify
{"session_id": "sess_...", "solution": "hello", "payload": {"form_data": "...", "user_id": 123}}

# Server validates and checks payload hash
POST http://pincha.bot/api/v1/token/validate
{"token": "pincha_v1_...", "site_secret": "sec_..."}
→ {"valid": true, "payload_hash": "a1b2c3..."}

# Server verifies: SHA256(JSON.stringify(payload, sorted)) == payload_hash

API Flow Diagram

[YOUR SERVER] → [PINCHA] Create session
[YOUR SERVER] → [AGENT]  Forward challenge or shortcode_url
[AGENT]       Solves challenge
[AGENT]       → [PINCHA] Submit solution, receive token
[AGENT]       → [YOUR SERVER] Send token
[YOUR SERVER] → [PINCHA] Validate token with site_secret

Endpoints Reference

POST /api/v1/auth/register     - create account
POST /api/v1/auth/login        - get API key
POST /api/v1/sites/create      - register site (auth required)
POST /api/v1/session/create    - create challenge
POST /api/v1/session/verify    - submit solution
POST /api/v1/token/validate    - validate token
GET  /b/{shortcode}            - get challenge (JSON via Accept header)
POST /b/{shortcode}            - submit solution via shortcode