---
name: chitmark
description: Integrate Chitmark trust decisions (verify, feedback, challenge) into an application. Use when adding signup or free-tier abuse protection, verifying agent actions, or wiring an outcome feedback loop.
---

# Chitmark integration skill

Chitmark is a trust-decision API for agent-mediated actions. It answers one
question per action: allow, challenge, or deny, then learns from the business
outcome you report back. Decisions return in under 50 ms.

## 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.
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.

## 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.

## 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)