# captcha — skill (for AI agents)

**Instructions:** This file is returned by **GET /** as `text/markdown`. When a user or workflow needs captcha recognition, **fetch GET /** on the service base URL (or read `skill.md` from the repo) and follow the HTTP contract below. Prefer **POST /** with JSON; do not assume other routes.

## What it does

**POST /** accepts JSON with required **`input`**: an image as an `http(s)` URL, a `data:image/...;base64,...` string, or raw base64. Optional fields **`kind`**, **`length`**, and **`prompt`** steer the recognition instruction when the deployment supports them. The vision model used by the server is fixed per deployment (not selectable by clients). The service returns JSON containing the recognized captcha text. How the image is processed on the server is not part of this contract.

## Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/` | This skill document (`skill.md`) |
| GET | `/health` | `{"ok":true}` liveness |
| POST | `/` | Recognize captcha (JSON body) |

## POST / request body

**Required:** **`input`**. **Optional:** **`kind`**, **`length`**, **`prompt`** (ignored by deployments that do not implement them).

```json
{
  "input": "<required: url | data URL | raw base64>",
  "kind": "digits",
  "length": 4,
  "prompt": "<optional: full custom instruction; overrides kind/length>"
}
```

- **`input`** (required): trimmed string — `http(s)://...` image URL, `data:image/png;base64,...`, or base64-only payload.
- **`kind`** (optional): narrows the expected character set for recognition. **If omitted, the character set is not restricted** (digits, Latin letters, and/or Chinese characters, as in the image).
  - `digits` — digits `0-9` only  
  - `letters` — Latin `A-Z` / `a-z` only  
  - `alnum` — Latin letters and digits only  
  - `chinese` — Chinese (Han) characters as shown  
  - `mixed` — same as omitting `kind` (no restriction)  
  Aliases accepted by some deployments include `numeric` / `digit` → `digits`, `alpha` → `letters`, `alphanumeric` → `alnum`, `zh` / `han` / `中文` → `chinese`.
- **`length`** (optional): expected length hint for the model.
  - A **positive number** means exactly that many characters (e.g. `4`).
  - Or an object: `{ "exact": 6 }`, `{ "min": 2, "max": 4 }`, `{ "min": 4 }`, or `{ "max": 8 }`.
- **`prompt`** (optional): if set to a non-empty string, it replaces the built-in captcha instruction (and **`kind` / `length` are not applied**).

## POST / success response

```json
{
  "ok": true,
  "text": "<recognized string>",
  "raw": "<auxiliary string; treat as opaque unless you need it>",
  "meta": {
    "inputKind": "url | dataUrl | base64",
    "requestId": "<opaque id; include in support tickets if asked>"
  }
}
```

Response fields do not describe how recognition is implemented on the server.

## POST / error response

```json
{
  "ok": false,
  "error": "<message>",
  "meta": { "requestId": "...", "inputKind": "..." }
}
```

Typical status codes: **400** (bad or unsupported `input`), **502** (recognition could not be completed), **500** (unexpected server error).

## curl

Examples use **https://captcha.ctrl1.com**; substitute your own base URL if needed.

```bash
# Health
curl -sS "https://captcha.ctrl1.com/health"

# Load this skill from the running server
curl -sS "https://captcha.ctrl1.com/"

# Recognize — raw base64 (short PNG example)
curl -sS -X POST "https://captcha.ctrl1.com/" \
  -H "Content-Type: application/json" \
  -d "{\"input\":\"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==\"}"

# Recognize — data URL
curl -sS -X POST "https://captcha.ctrl1.com/" \
  -H "Content-Type: application/json" \
  -d "{\"input\":\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==\"}"

# Recognize — image URL (must be reachable from the service host)
curl -sS -X POST "https://captcha.ctrl1.com/" \
  -H "Content-Type: application/json" \
  -d "{\"input\":\"https://example.com/captcha.png\"}"

# Recognize — 4-digit numeric captcha (optional hints)
curl -sS -X POST "https://captcha.ctrl1.com/" \
  -H "Content-Type: application/json" \
  -d "{\"input\":\"https://example.com/captcha.png\",\"kind\":\"digits\",\"length\":4}"
```

## Node.js (global fetch)

```javascript
const BASE = process.env.CAPTCHA_BASE || "https://captcha.ctrl1.com";

async function recognizeCaptcha(input, options = {}) {
  const body = { input, ...options };
  const res = await fetch(BASE + "/", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  const data = await res.json().catch(() => ({}));
  if (!res.ok) {
    const err = new Error(data.error || res.statusText);
    err.status = res.status;
    err.body = data;
    throw err;
  }
  return data;
}

// Example — no kind: character set unrestricted
recognizeCaptcha("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==")
  .then((r) => console.log(r.text))
  .catch((e) => console.error(e.status, e.message));

// Example — optional hints
recognizeCaptcha("https://example.com/c.png", { kind: "alnum", length: 6 })
  .then((r) => console.log(r.text))
  .catch((e) => console.error(e.status, e.message));
```

## Agent checklist

1. **Discover:** Call `GET /` on the live base URL if you need the authoritative contract for that deployment.
2. **Call:** `POST /` with `Content-Type: application/json` and body at least `{ "input": "<...>" }`; add `kind` / `length` only when you want to constrain charset or length (omit `kind` for no charset restriction).
3. **Privacy:** Avoid pasting full `input` (especially long base64) into public chats or logs; treat it like sensitive image data.
4. **Limits:** Keep payloads within normal JSON size limits for your environment; very large bodies may be rejected.