API Documentation

Integrate compliance checks and AI-agent detection into your applications with the AI DECISIONS API.

Authentication

All API requests require an X-API-Key header.

http

GET /compliance/status HTTP/1.1
Host: api.aidecisions.ai
X-API-Key: your-api-key

Get your API key by registering a tenant via POST /tenants/register or from the dashboard.

Quick Start

Python

python

from ai_decisions_client import AiDecisionsClient

client = AiDecisionsClient(
    base_url="https://api.aidecisions.ai",
    api_key="ak_your_key_here",
)

result = client.transaction_check(
    amount=9500.00,
    sender="Acme Trading Ltd",
    receiver="Global Logistics SA",
    sender_jurisdiction="panama",
    currency="USD",
)

print(result["risk_level"])       "color:#6b7280"># "high"
print(result["recommendation"])   "color:#6b7280"># "block_and_review"

TypeScript

typescript

import { AiDecisionsClient } from "@ai-decisions/client";

const client = new AiDecisionsClient({
  baseUrl: "https:">//api.aidecisions.ai",
  apiKey: "ak_your_key_here",
});

const result = await client.transactionCheck({
  amount: 9500.0,
  sender: "Acme Trading Ltd",
  receiver: "Global Logistics SA",
  sender_jurisdiction: "panama",
  currency: "USD",
});

console.log(result.risk_level);       "color:#6b7280">// "high"
console.log(result.recommendation);   "color:#6b7280">// "block_and_review"

POST /compliance/transaction-check

Check a single transaction for compliance risk. Returns a risk level, score, recommendation, and explanation.

Request Body

json

{
  "amount": 9500.00,
  "sender": "Acme Trading Ltd",
  "receiver": "Global Logistics SA",
  "sender_jurisdiction": "panama",
  "receiver_jurisdiction": "cayman_islands",
  "currency": "USD",
  "graph_centrality": 0.45,
  "gnn_score": 0.72
}

Response

json

{
  "risk_score": 0.78,
  "risk_level": "high",
  "risk_factors": [
    {
      "rule": "high_risk_sender_jurisdiction",
      "detail": "Sender jurisdiction (panama) is in FSI top-10",
      "severity": "high"
    },
    {
      "rule": "potential_structuring",
      "detail": "Amount $9,500 is 95% of $10,000 CTR threshold",
      "severity": "high"
    }
  ],
  "recommendation": "block_and_review",
  "components": {
    "graph_centrality": 0.45,
    "gnn_score": 0.72,
    "rule_score": 1.0
  }
}

Risk Levels

high — Block and escalate
medium — Enhanced review
low — Proceed normally

Recommendations

block_and_review
enhanced_due_diligence
proceed

POST /compliance/agent-detection

Detect AI-agent behavior from a set of transaction patterns. Submit multiple transactions for a single account and receive a classification.

Request Body

json

{
  "transactions": [
    {
      "timestamp": "2026-04-04T08: 00: 01Z",
      "amount": 499.99,
      "sender": "wallet_0x1a2b",
      "receiver": "wallet_0x3c4d"
    },
    {
      "timestamp": "2026-04-04T08: 00: 02Z",
      "amount": 499.99,
      "sender": "wallet_0x1a2b",
      "receiver": "wallet_0x5e6f"
    },
    {
      "timestamp": "2026-04-04T08: 00: 03Z",
      "amount": 499.99,
      "sender": "wallet_0x1a2b",
      "receiver": "wallet_0x7g8h"
    }
  ]
}

Response

json

{
  "agent_probability": 0.85,
  "classification": "likely_agent",
  "indicators": [
    {
      "indicator": "perfect_periodicity",
      "detail": "Transaction intervals vary by less than 5%",
      "score": 0.9
    },
    {
      "indicator": "amount_clustering",
      "detail": "Transaction amounts vary by less than 2%",
      "score": 0.8
    }
  ],
  "transaction_count": 3,
  "interval_data": [1.0, 1.0],
  "amount_data": [499.99, 499.99, 499.99],
  "weekday_counts": { "Fri": 3 },
  "topology": {
    "nodes": [
      { "id": "wallet_0x1a2b", "type": "wallet", "risk": 0.85 },
      { "id": "wallet_0x3c4d", "type": "wallet", "risk": 0.0 }
    ],
    "edges": [
      { "source": "wallet_0x1a2b", "target": "wallet_0x3c4d", "amount": 499.99, "count": 1 }
    ]
  }
}

Classification Values

likely_agent — High confidence of automated behavior
possibly_agent — Some automated signals detected
likely_human — Behavior consistent with human activity

Rate Limits

Rate limits are enforced per API key based on your subscription tier. Limits reset daily at 00:00 UTC.

Tier	Daily API Calls	Compliance Checks / Day
Research	100	20
Analyst	500	100
Professional	2,000	500
Enterprise	10,000	2,000

Rate Limit Headers

X-RateLimit-Limit — Maximum requests allowed per day

X-RateLimit-Remaining — Requests remaining in the current window

X-RateLimit-Reset — UTC timestamp when the limit resets

X-Compliance-RateLimit-Limit — Maximum compliance checks per day

X-Compliance-RateLimit-Remaining — Compliance checks remaining

When you exceed your rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating the number of seconds to wait before retrying.

Error Codes

Code	Description
401	Invalid or missing API key. Include a valid key in the X-API-Key header.
403	Feature not available on your current tier. Upgrade your plan to access this endpoint.
422	Validation error. Check the request body against the schema above.
429	Rate limit exceeded. Retry after the number of seconds in the Retry-After header.

SDKs

Official client libraries for the AI DECISIONS API.

Python

bash

pip install ai-decisions

Source: sdk/python

TypeScript

bash

npm install @ai-decisions/client

Source: sdk/typescript