API Documentation

Entropy0 API Reference

The Entropy0 Trust Control Plane evaluates external targets in the context of intended agent interactions and policy posture, returning machine-readable action decisions with evidence, uncertainty, and bounded validity. Underlying Trust, Threat, and Deviation scores are also available for direct integration.

Live Playground

Scan any domain — see trust, threat & intent signals instantly.

Try:

Authentication

Both headers are supported — use whichever fits your client:

X-API-Key: sk_ent0_xxxx

Authorization: Bearer sk_ent0_xxxx

Generate keys from your account dashboard.

Endpoints

POST /v1/decideRecommended
POST /v1/decide/batch
Lower-level primitives
POST /v1/domain/score
POST /v1/domain/score/batch

Sandbox

Validate scans interactively: Domain Scanner →

Understand the decision logic: Decision Model →

POST /v1/decide

Control PlaneRecommended

Evaluates a target in the context of the intended agent interaction and policy posture. Returns a machine-readable recommended action — not a truth claim about the target.

Request

curl -X POST https://entropy0.ai/api/v1/decide \
  -H "X-API-Key: sk_ent0_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "target":      { "type": "domain", "value": "secure-payments-example.com" },
    "interaction": { "kind": "navigate", "mode": "read_only", "sensitivity": "medium" },
    "policy":      { "profile": "balanced" }
  }'

target.type — domain available on all plans. url requires Team or above.

options.include_evidence — defaults to true. Omit options entirely to receive evidence highlights in every response.

Response

{
  "request_id": "dec_a1b2c3d4e5f6a7b8c9d0e1f2a3",
  "version": "2026-03-19",
  "target": { "type": "domain", "value": "secure-payments-example.com", "normalized": "secure-payments-example.com" },
  "interaction": { "kind": "navigate", "mode": "read_only", "sensitivity": "medium" },
  "policy_applied": { "profile": "balanced", "policy_version": "p_2026_03_v1" },
  "scores": {
    "trust":     { "score": 34, "confidence": 0.76 },
    "threat":    { "score": 68, "confidence": 0.72 },
    "deviation": { "score": 81, "confidence": 0.84 }
  },
  "decision": {
    "recommended_action": "sandbox",
    "action_confidence": 0.74,
    "reason_codes": ["NEWLY_REGISTERED_DOMAIN", "HIGH_INFRASTRUCTURE_DEVIATION", "LOW_REPUTATION_EVIDENCE"],
    "decision_rationale": {
      "primary_reason_codes": ["NEWLY_REGISTERED_DOMAIN", "HIGH_INFRASTRUCTURE_DEVIATION"],
      "uncertainty_influencers": []
    }
  },
  "uncertainty": {
    "state": "medium",
    "requires_human_review": false,
    "drivers": ["Moderate confidence — some evidence gaps"]
  },
  "evidence": {
    "highlights": [
      { "code": "NEWLY_REGISTERED_DOMAIN", "label": "Newly registered domain", "impact": "negative", "strength": 0.81 },
      { "code": "HIGH_INFRASTRUCTURE_DEVIATION", "label": "Infrastructure differs materially from expected norms", "impact": "negative", "strength": 0.77 }
    ],
    "highlights_truncated": false,
    "source_count": 5
  },
  "validity": { "evaluated_at": "2026-03-19T20:41:22Z", "valid_until": "2026-03-19T20:46:22Z", "ttl_seconds": 300 }
}

validity.valid_until — decisions are valid for 300 seconds from evaluation. After valid_until, re-submit the request to get a fresh evaluation. Cached scan data is re-used within the TTL window; a full re-scan is triggered on miss.

Action vocabulary

Action	Meaning
proceed	Normal automated interaction is acceptable.
proceed_with_caution	Continue with reduced trust assumptions — avoid credential submission, prefer read-only.
sandbox	Interact only in a constrained or isolated environment.
escalate_to_human	Pause automation and request human review.
deny	Automated action should not proceed under this policy and interaction context.

Policy profiles

open

Tolerates novelty. Favors proceed_with_caution over sandbox when risk is not material.

balanced

Default enterprise-safe posture with no directional bias.

strict

Sandboxes or escalates faster under ambiguity.

critical

Treats unknowns conservatively. Hardest on sensitive interactions.

Why use /v1/decide instead of /v1/domain/score?

/v1/domain/score returns raw Trust, Threat, and Deviation numbers — useful when you want to build your own decision logic or store signals for analysis.

/v1/decide takes those same scores and applies an interaction context (what is the agent about to do?) and a policy profile (how risk-tolerant is this workflow?) to emit a single recommended_action. Use it when you want the control plane to make the routing call so your automation doesn't have to.

POST /v1/decide/batch

Control Plane

Evaluate up to 25 domains in a single request. All targets are resolved in parallel — latency is bounded by the slowest target, not the sum. Shared interaction and policy apply to all items. Per-item errors do not block other results.

Request

curl -X POST https://entropy0.ai/api/v1/decide/batch \
  -H "X-API-Key: sk_ent0_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [
      { "type": "domain", "value": "github.com" },
      { "type": "domain", "value": "secure-login-verify.xyz" },
      { "type": "domain", "value": "paypal.com" }
    ],
    "interaction": { "kind": "fetch", "mode": "read_only", "sensitivity": "medium" },
    "policy":      { "profile": "balanced" }
  }'

Response

{
  "batch_id": "bat_a1b2c3d4e5f6a7b8c9d0e1f2a3",
  "version": "2026-03-19",
  "policy_applied": { "profile": "balanced", "policy_version": "p_2026_03_v1" },
  "interaction": { "kind": "fetch", "mode": "read_only", "sensitivity": "medium" },
  "summary": { "total": 3, "success": 2, "errors": 1 },
  "results": [
    {
      "status": "ok",
      "index": 0,
      "request_id": "dec_x1y2z3...",
      "target": { "type": "domain", "value": "github.com", "normalized": "github.com" },
      "decision": {
        "recommended_action": "proceed",
        "action_confidence": 0.91,
        "reason_codes": ["LONG_LIVED_DOMAIN", "STRONG_SSL", "HIGH_TRUST_SCORE"],
        "decision_rationale": {
          "primary_reason_codes": ["HIGH_TRUST_SCORE"],
          "uncertainty_influencers": []
        },
        "uncertainty": { "state": "low", "requires_human_review": false, "drivers": [] },
        "scores": {
          "trust":     { "score": 96, "confidence": 0.88 },
          "threat":    { "score": 0,  "confidence": 0.85 },
          "deviation": { "score": 17, "confidence": 0.80 }
        },
        "validity": {
          "evaluated_at": "2026-04-09T10:00:00Z",
          "valid_until":  "2026-04-09T10:05:00Z",
          "ttl_seconds":  300
        },
        "evidence": {
          "highlights": [
            { "code": "HIGH_TRUST_SCORE", "label": "Strong infrastructure posture", "impact": "positive", "strength": 0.91 }
          ],
          "highlights_truncated": false,
          "source_count": 6
        }
      }
    },
    {
      "status": "ok",
      "index": 1,
      "request_id": "dec_a2b3c4...",
      "target": { "type": "domain", "value": "secure-login-verify.xyz", "normalized": "secure-login-verify.xyz" },
      "decision": {
        "recommended_action": "deny",
        "action_confidence": 0.87,
        "reason_codes": ["PHISHING_KEYWORD", "NEWLY_REGISTERED_DOMAIN", "NO_EMAIL_AUTH"],
        "decision_rationale": {
          "primary_reason_codes": ["PHISHING_KEYWORD", "NEWLY_REGISTERED_DOMAIN"],
          "uncertainty_influencers": []
        },
        "uncertainty": { "state": "low", "requires_human_review": false, "drivers": [] },
        "scores": {
          "trust":     { "score": 32, "confidence": 0.76 },
          "threat":    { "score": 74, "confidence": 0.82 },
          "deviation": { "score": 63, "confidence": 0.79 }
        },
        "validity": {
          "evaluated_at": "2026-04-09T10:00:00Z",
          "valid_until":  "2026-04-09T10:05:00Z",
          "ttl_seconds":  300
        },
        "evidence": {
          "highlights": [
            { "code": "PHISHING_KEYWORD", "label": "Domain name contains phishing keywords", "impact": "negative", "strength": 0.85 },
            { "code": "NEWLY_REGISTERED_DOMAIN", "label": "Registered less than 90 days ago", "impact": "negative", "strength": 0.81 }
          ],
          "highlights_truncated": false,
          "source_count": 5
        }
      }
    },
    {
      "status": "error",
      "index": 2,
      "target": { "type": "domain", "value": "paypal.com" },
      "error": { "code": "TARGET_UNRESOLVABLE", "message": "Could not evaluate 'paypal.com'." }
    }
  ]
}

summary.success / errors — partial success is valid. Check each item's status field independently.

Max batch size — 25 targets per request. Use options: { "include_evidence": false } to reduce payload size for high-frequency calls.

POST /v1/domain/score

Signal primitive

Scores a domain or URL. Returns raw Trust, Threat, and Deviation scores with evidence and coverage metadata. Use this when you need the underlying signal breakdown rather than a policy-shaped action decision.

curl -X POST https://entropy0.ai/api/v1/domain/score \
  -H "Authorization: Bearer sk_ent0_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "input": "example.com" }'

{
  "scanId": "uuid",
  "input": "example.com",
  "inputType": "domain",
  "trustScore": 82,
  "threat": { "score": 18, "level": "low" },
  "scoreDetails": { "powerLawAnomalyScore": 12, "anomalyRarity": "typical" },
  "analysis": {
    "coverage":   { "coverageScore": 100, "coveredCount": 7 },
    "confidence": { "confidenceScore": 91, "confidenceLevel": "high" }
  },
  "scan_version": "2.0.2",
  "scoring_version": "0.7.0"
}

POST /v1/domain/score/batch

Signal primitive

Scores multiple domains in one request. Plan-gated limits apply: Developer (50), Team (500), Platform (5,000).

curl -X POST https://entropy0.ai/api/v1/domain/score/batch \
  -H "Authorization: Bearer sk_ent0_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "domains": ["example.com", "paypal.com"] }'

Status codes and error model

All errors follow a standard envelope: { error: { type, code, message, param, request_id } }

Status	Meaning
200	Successful response.
400	Invalid or missing request fields.
401	Missing or invalid API key.
403	Valid key but plan does not permit this operation (e.g., URL target requires Team+).
409	Concurrency lock active for the same principal.
422	Target cannot be evaluated — does not resolve or is structurally invalid.
429	Rate limit or plan quota exceeded. Check Retry-After header.
500	Internal evaluation failure. Safe to retry.
503	Scoring engine temporarily unavailable. Retry with exponential backoff.