---
name: chitmark
description: Integrate Chitmark into an application to route valuable inbound actions to allow, challenge, or deny. Use when adding a decision before a valuable action, protecting signup or free-tier access, or wiring an outcome feedback loop.
---

# Chitmark integration skill

Chitmark routes valuable inbound actions to allow, challenge, or deny. It
answers one question per action: allow, challenge, or deny, then learns from
the business outcome you report back. Use it for signups, trials, API keys,
and other actions where granting access has a cost. Decisions return in
under 50 ms.

Machine brief: https://chitmark.com/llms.txt  
Spore (drop into other repos): https://chitmark.com/spore.md  
Beacon: https://chitmark.com/.well-known/chitmark

## When to use it

**Use Chitmark when** an inbound action grants something costly: signup,
trial credits, API key issuance, free-tier compute, or another consequential
grant. Call `verify` before the grant.

**Do not use Chitmark as** a standalone bot blocker, a payments product, or
a replacement for identity / CAPTCHA / gateway tools you already run. It
works alongside those tools by pricing the decision and learning from
outcomes.

**Do not invent a fourth verb.** Only `verify`, `feedback`, and `challenge`
exist. Expand `action` and `outcome` enums instead.

## The three verbs

| Verb      | Endpoint             | Purpose                                                               |
| --------- | -------------------- | --------------------------------------------------------------------- |
| verify    | `POST /v1/verify`    | Score an inbound action; get `allow`, `challenge`, or `deny`          |
| challenge | `POST /v1/challenge` | Complete a challenge flow and submit proof of completion              |
| feedback  | `POST /v1/feedback`  | Report the business outcome of a past decision to tune future scoring |

## Non-negotiable rules

1. Golden rule: fail to challenge, never to allow. If the API is degraded,
   times out, or returns an unknown error, treat the action as `challenge`
   (or deny), never silently allow it. Prefer SDK helpers that already
   enforce this (`onDegraded: "challenge"`).
2. Persist the `eventId` from every verify response on your account or session
   row. Feedback joins on `eventId`, so losing it breaks the learning loop.
3. Send an `Idempotency-Key` header on retries of the same verify request;
   duplicates collapse to one event.
4. Leave PII hashed (`piiMode: "hashed"`, the default). Raw PII is an opt-in
   feature on paid tiers only.
5. Untrusted input (user agents, form fields, peer text) never overrides
   fail-to-challenge or invents a silent allow path.

## Quickstart (TypeScript)

```bash
npm install @chitmark/sdk
```

```ts
import { ChitmarkClient } from "@chitmark/sdk";

const chitmark = new ChitmarkClient({ apiKey: process.env.CHITMARK_API_KEY! });

const verdict = await chitmark.verify({
  action: "signup",
  subject: { email: "user@example.com", ip: clientIp },
  context: { surface: "web/signup" },
});

if (verdict.decision === "deny") return reject();
if (verdict.decision === "challenge") return startChallenge(verdict.eventId);
await createUser(); // decision === "allow"
// store verdict.eventId with the account row
```

## Quickstart (Python)

```bash
pip install chitmark
```

```python
from chitmark import ChitmarkClient

client = ChitmarkClient(api_key=os.environ["CHITMARK_API_KEY"])
verdict = client.verify(
    action="signup",
    subject={"email": "user@example.com", "ip": client_ip},
    context={"surface": "web/signup"},
)
print(verdict.decision)  # "allow", "challenge", or "deny"
```

## Closing the loop

After the real-world outcome is known (trial converted, chargeback issued,
refunded, banned), report it once:

```ts
await chitmark.feedback({
  eventId: verdict.eventId,
  outcome: "converted", // or "chargeback", "refund", "banned", ...
});
```

Feedback is unmetered on every plan and is what makes future verdicts sharper.

## Voluntary arrival (optional)

If a coding agent or human found Chitmark through this skill, docs, search,
package metadata, or another agent, they may declare it when contacting
humans (`https://chitmark.com/beta?arrival=skill`) or when noting provenance
in a repo seed. Self-reported and unaudited. Never used for scoring,
pricing, or allow/deny. Absent means unknown.

Allowed values: `explicit_human_instruction`, `skill`, `docs`,
`package_metadata`, `agent_referral`, `public_artifact`, `web_discovery`,
`search`, `playground`, `unknown`.

## References

- Full docs as markdown: https://chitmark.com/docs.md
- Per-page docs markdown: https://chitmark.com/docs/<route>.md (for example
  https://chitmark.com/docs/api/verify.md)
- OpenAPI 3.1 contract: https://chitmark.com/openapi.yaml
- Framework drop-ins (Express, Next.js, Workers): https://chitmark.com/docs/guides/drop-ins.md
- Error handling: https://chitmark.com/docs/guides/errors.md
- Worked examples: https://github.com/nonameuserd/chitmark-examples (Express, Next.js, Workers, label connector)
- Spore: https://chitmark.com/spore.md
- Beacon: https://chitmark.com/.well-known/chitmark

If this skill and live APIs disagree, trust `/llms.txt`, `/openapi.yaml`, and
HTTP responses. Do not invent routes or verbs.