# Bynn for AI Agents

Machine-readable guide for AI agents (Claude, ChatGPT, Gemini, or any MCP-compatible
client) to use **Bynn** — document fraud detection, KYC, age verification, content
moderation, face search, and AutoDoc — programmatically, without human hand-holding.

The fastest path is the **Bynn MCP server**. You can also call the REST API directly.

## Quick reference

| Thing | Value |
|---|---|
| MCP server | `https://mcp.bynn.com/` (Streamable HTTP) |
| Get an access token | `https://dashboard.bynn.com/authenticate` (log in, then copy the token) |
| Auth header (MCP + API) | `Authorization: Bearer <YOUR_BYNN_TOKEN>` |
| REST API base | `https://api.bynn.com/v1` |
| Full API spec (OpenAPI 3.0) | `https://api.bynn.com/openapi.json` |
| Dashboard | `https://dashboard.bynn.com` |
| Docs | `https://docs.bynn.com` |

Token scope: the token acts with **your** account's permissions and is long-lived
(~3 years). Treat it like a password. New usage consumes account credits; top up in the
dashboard billing section.

## Complete flow

1. Log in to `https://dashboard.bynn.com` and open **`/authenticate`**.
2. Generate an access token and copy it.
3. Connect an MCP client to `https://mcp.bynn.com/` with the token (config below), **or**
   call `https://api.bynn.com/v1` directly with the same `Authorization: Bearer` header.
4. Discover capabilities with the `describe_api` tool (MCP) or `GET /openapi.json` (REST).
5. Call the tool/endpoint for your task (examples below).

## Using Bynn via MCP (recommended)

Add Bynn as an HTTP MCP server:

```json
{
  "mcpServers": {
    "bynn": {
      "type": "http",
      "url": "https://mcp.bynn.com/",
      "headers": { "Authorization": "Bearer <YOUR_BYNN_TOKEN>" }
    }
  }
}
```

**One token unlocks everything.** The server resolves the correct credential per tool
automatically — you never manage API keys by hand:

| Tool group | How the server authenticates it |
|---|---|
| billing, users, websites, reasoning, autodoc, moderation, face | forwards your dashboard token |
| documents, age verification, agemin checks | fetches your org's private key automatically |
| verification sessions (create) | fetches your org's public key automatically |

MCP tools are invoked by the model when relevant (they are not slash commands). Just ask:
"run a fraud check on this document", "is this image AI-generated?", "estimate the age in
this photo", "create a KYC session for this user".

### Key tools

- `describe_api` — returns the full OpenAPI 3.0 spec. Call this first to discover everything.
- `submit_document` → `get_document` — full document fraud analysis (see below).
- `detect_ai_generated_image` — is a single image AI-generated?
- `check_age` — estimate age / detect minors from a face image.
- `create_session` — start a hosted KYC / identity-verification session.
- `create_moderation_inference` — run any moderation/detection model on content.
- `create_face_collection` / `enroll_face` / `search_faces` — face search.

Image inputs accept `file_path` (local/self-hosted server), `image_url`, or `base64_image`.

## Using the REST API directly

Send your token (or a `private_…` API key) as a Bearer header. See
`https://api.bynn.com/openapi.json` for every path, parameter, and response schema.

### Detect an AI-generated image

```bash
curl -X POST https://api.bynn.com/v1/moderation/image \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "model": "ai-generated-image", "image_url": "https://example.com/file.jpg" }'
```

```json
{
  "result": {
    "is_ai_generated": true,
    "ai_probability": 0.9998,
    "top_generator": { "name": "openai_gpt_image", "probability": 0.96 }
  }
}
```

### Estimate age

```bash
curl -X POST https://api.bynn.com/v1/moderation/image \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "model": "age-detection", "image_url": "https://example.com/face.jpg" }'
```

Returns per-face `age`, `from_age`/`to_age`, `is_minor`, `challenge_25`, `sex`, `confidence`.

### Full document fraud detection (asynchronous)

Runs the complete forensic pipeline — forgery-template matching, tampering & manipulation,
font/consistency, signature validation, deepfake + AI-generation, MRZ/barcode/EXIF,
classification, and an overall risk score — on IDs, passports, invoices, contracts, etc.

```bash
# 1) submit
curl -X POST https://api.bynn.com/v1/documents \
  -H "Authorization: Bearer <YOUR_PRIVATE_KEY>" \
  -F "file=@/path/to/document.pdf" \
  -F "reference_id=my-ref-123"
# -> { "submission_id": "document_…", "document_id": "…", "status": "received" }

# 2) poll ~every 3 minutes until status == "analyzed"
curl https://api.bynn.com/v1/documents/<submission_id> \
  -H "Authorization: Bearer <YOUR_PRIVATE_KEY>"
# -> analysis_risk_status, analysis_risk_score, ai_generated_score, tampering_results, …
```

## Error handling

| Status | Meaning | What an agent should do |
|---|---|---|
| 401 | Missing/invalid token | Get a token at `https://dashboard.bynn.com/authenticate` and retry |
| 402 | Insufficient balance | Top up credits in the dashboard, then retry |
| 403 | Not permitted for your role/plan | Use an account with the required role/plan |
| 404 | Not found | Check the id (e.g. document/session identifier) |
| 413 / 415 | Too large / unsupported type | Documents ≤ 64 MB; images/PDF only (jpg, jpeg, png, pdf) |
| 422 | Validation error | Fix the parameters per the error message |
| 429 | Rate limited | Back off and retry |

Errors are returned as `{ "error": { "type": "...", "message": "..." } }`.

## Suggested agent algorithm

1. Ensure you have a Bynn token. If not, direct the user to `https://dashboard.bynn.com/authenticate`.
2. Connect to `https://mcp.bynn.com/` (or the REST API) with the token.
3. Call `describe_api` (or fetch `/openapi.json`) to confirm available capabilities.
4. Pick the tool for the task:
   - authenticity of a document → `submit_document`, then poll `get_document`
   - AI-generated image check → `detect_ai_generated_image`
   - age / minor detection → `check_age`
   - end-user identity verification → `create_session`
   - content moderation → `create_moderation_inference`
5. Handle errors per the table above (auth → get token; 402 → top up).
6. Return the structured result to the user.

## References

- MCP server: `https://mcp.bynn.com/`
- Get a token: `https://dashboard.bynn.com/authenticate`
- OpenAPI spec: `https://api.bynn.com/openapi.json`
- API docs: `https://docs.bynn.com`
- Document fraud detection: `https://www.bynn.com/document-fraud-detection-tool`