Skip to guide
Documentation/How the Carmen API works

How the Carmen API works.

Send content to one endpoint and get back a verdict.

01

One endpoint

POST /api/analyze-content. Send text, a link, or files. Carmen works out what it is. You get back the risk level, the reasons, and one thing to do, already written for a person.

Carmen API

Sample request

POST /api/analyze-content
Authorization: Bearer bgr_xxxx_...
{
  "content": {
    "text": "Your parcel is on hold. Pay the release fee here: parcel-redelivery.info"
  },
  "options": {
    "createCase": true
  }
}
Sample request.
02

Sync or async

A bare link, a person lookup or a deepfake check answers in the same response. A message or an email is queued: you get a job id and a result link, and you poll it. The response tells you which happened, in the mode field.

Carmen API

Sample response

202
{
  "job_id": "...",
  "status": "pending",
  "mode": "async",
  "search_type": "scam",
  "links": {
    "status": "/api/jobs/<id>",
    "result": "/api/jobs/<id>/result"
  }
}
Sample response.
03

The verdict

clean, unknown_fresh, suspicious or malicious. Show it as Low (clean), Medium (unknown_fresh, suspicious) or High (malicious). Plus confidence (low, medium, high), a headline under 280 characters, a recommended action under 500, and up to six pieces of evidence, each with a source, the signal, a weight and what was observed.

Carmen API

Sample response

200
{
  "job_id": "...",
  "status": "completed",
  "mode": "sync",
  "search_type": "safety",
  "result": {
    "verdict": "malicious",
    "confidence": "high",
    "headline": "This link points to a four day old domain already listed as phishing.",
    "recommended_action": "Do not open it. If you entered card details, call your card issuer.",
    "evidence_trail": [
      {
        "source": "rdap",
        "signal": "domain_age",
        "weight": 0.8,
        "observation": "Registered 4 days ago"
      }
    ]
  }
}
Sample response.
04

Depth and credits

Carmen Light uses 5 credits, Carmen Basic 25 and Carmen Advanced 250, which includes the written report. Every call you make uses credits. The same content sent again within an hour returns the same verdict.

Carmen API

Depth and credits

JUST_THE_FACTS, FAST: 5 credits
ESSENTIALS, STANDARD: 25 credits
DEEP_DIVE: 250 credits, report included
Depth and credits.
05

Reports

Ask for one with reportFormats and fetch it as JSON, PDF or HTML when the job is done.

Carmen API

Reports

GET /api/reports/{jobId}?format=json|pdf|html
Reports.

Preview