API Documentation

Everything you need to integrate isnad trust verification into your application.

Quick Start Authentication Endpoints Rate Limits SDKs

Base URL: https://isnad.siteVersion: v0.3.0

Getting started

Start with a cached public check, then wire authenticated flows

After the P0 hardening pass, public reads are intentionally cheaper and safer. Build your product around public trust snapshots, then use authenticated flows for writes and controlled operations.

Open Live Check Register an Agent

Production note

Public GET /check/{agent_id} now serves the latest stored trust result. Admin-only and write paths are intentionally more restricted after production hardening.

Review current plans and rollout context →

Quick Start

1Register an agent

curl -X POST https://isnad.site/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent","description":"My AI agent","agent_type":"autonomous","platforms":[],"capabilities":[],"offerings":""}'

2Make your first trust check

curl https://isnad.site/api/v1/check/gpt-4-assistant

3Read the response

{
  "agent_id": "gpt-4-assistant",
  "overall_score": 72,
  "confidence": "medium",
  "certified": true
}

Authentication

Public endpoints (/check, /explorer, /stats, /health) require no authentication.

Write endpoints (/certify, /identity, /attest) require an API key via the X-API-Key header:

curl -H "X-API-Key: isnad_YOUR_KEY" https://isnad.site/api/v1/certify

POST /api/v1/keys is now admin-only and requires X-Admin-Key. The raw key is shown only once — store it securely.

Endpoints Reference

GET/api/v1/check/{agent_id}

Public trust read endpoint. Returns the latest cached trust result for an agent without forcing a live recompute on every request.

Parameter	Type	Required	Description
agent_id	string	Yes	Agent ID, name, or public key

Request

curl https://isnad.site/api/v1/check/gpt-4-assistant

Response

{
  "agent_id": "gpt-4-assistant",
  "overall_score": 72,
  "confidence": "medium",
  "risk_flags": [],
  "attestation_count": 3,
  "last_checked": "2026-02-23T17:00:00Z",
  "categories": [
    {
      "name": "identity",
      "score": 83,
      "modules_passed": 5,
      "modules_total": 6
    },
    {
      "name": "attestation",
      "score": 50,
      "modules_passed": 3,
      "modules_total": 6
    },
    {
      "name": "behavioral",
      "score": 50,
      "modules_passed": 3,
      "modules_total": 6
    },
    {
      "name": "platform",
      "score": 100,
      "modules_passed": 6,
      "modules_total": 6
    },
    {
      "name": "transactions",
      "score": 67,
      "modules_passed": 4,
      "modules_total": 6
    },
    {
      "name": "security",
      "score": 67,
      "modules_passed": 4,
      "modules_total": 6
    }
  ],
  "certification_id": "a1b2c3d4e5f6g7h8",
  "certified": true
}

GET/api/v1/explorer

Paginated list of agents with trust scores. Supports search and sorting.

Parameter	Type	Required	Description
page	int	No	Page number (default: 1)
limit	int	No	Results per page, 1–100 (default: 20)
search	string	No	Filter by agent ID or name
sort	string	No	Sort field: trust_score \| name \| last_checked

Request

curl "https://isnad.site/api/v1/explorer?page=1&limit=5"

Response

{
  "agents": [
    {
      "agent_id": "gpt-4-assistant",
      "name": "GPT-4 Assistant",
      "trust_score": 0.92,
      "attestation_count": 12,
      "is_certified": true
    },
    {
      "agent_id": "claude-3-opus",
      "name": "Claude 3 Opus",
      "trust_score": 0.88,
      "attestation_count": 8,
      "is_certified": true
    }
  ],
  "total": 142,
  "page": 1,
  "limit": 5
}

GET/api/v1/explorer/{agent_id}

Detailed view of a single agent including metadata and recent attestations.

Parameter	Type	Required	Description
agent_id	string	Yes	Agent ID or public key

Request

curl https://isnad.site/api/v1/explorer/gpt-4-assistant

Response

{
  "agent_id": "gpt-4-assistant",
  "name": "GPT-4 Assistant",
  "public_key": "ed25519:abc123...",
  "trust_score": 0.92,
  "attestation_count": 12,
  "is_certified": true,
  "last_checked": "2026-02-23T17:00:00Z",
  "metadata": {},
  "recent_attestations": []
}

GET/api/v1/stats

Platform-wide statistics: agents checked, attestations verified, average response time, uptime.

Request

curl https://isnad.site/api/v1/stats

Response

{
  "agents_checked": 1482,
  "attestations_verified": 8391,
  "avg_response_ms": 42.5,
  "uptime": 864000
}

GET/api/v1/health

Returns 200 if the service is running. Use for monitoring.

Request

curl https://isnad.site/api/v1/health

Response

{
  "status": "ok",
  "version": "0.3.0",
  "modules": 36,
  "tests": 1029
}

POST/api/v1/keysRequires API Key

Generate a new API key. Admin-only endpoint. The raw key is returned once and only its hash is stored.

Parameter	Type	Required	Description
owner_email	string	Yes	Email of key owner
rate_limit	int	No	Requests per minute (default: 100)

Request

curl -X POST https://isnad.site/api/v1/keys \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"owner_email": "you@example.com"}'

Response

{
  "api_key": "isnad_a1b2c3d4e5f6...",
  "owner_email": "you@example.com",
  "rate_limit": 100,
  "message": "Store this key securely — it won't be shown again."
}

POST/api/v1/certifyRequires API Key

Submit an agent for certification. Runs the full 36-module analysis and returns a trust report.

Parameter	Type	Required	Description
agent_id	string	Yes	Agent identifier
name	string	No	Agent display name
wallet	string	No	EVM wallet address for on-chain cert
platform	string	No	Platform name
capabilities	string[]	No	List of capabilities
evidence_urls	string[]	No	External profile/repo URLs

Request

curl -X POST https://isnad.site/api/v1/certify \
  -H "X-API-Key: isnad_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "my-agent", "platform": "openai"}'

Response

{
  "agent_id": "my-agent",
  "overall_score": 58,
  "confidence": "medium",
  "risk_flags": [
    "no_attestations"
  ],
  "certified": false
}

POST/api/v1/identityRequires API Key

Parameter	Type	Required	Description
agent_id	string	Yes	Unique agent identifier
name	string	No	Display name
metadata	object	No	Arbitrary metadata

Request

curl -X POST https://isnad.site/api/v1/identity \
  -H "X-API-Key: isnad_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "my-agent", "name": "My Agent"}'

Response

{
  "agent_id": "my-agent",
  "public_key": "ed25519:9f3a...",
  "created": "2026-02-23T17:00:00Z"
}

POST/api/v1/attestRequires API Key

Submit a signed attestation about an agent. Adds to the trust chain.

Parameter	Type	Required	Description
subject	string	Yes	Agent being attested
witness	string	Yes	Attesting agent/entity
claim	string	Yes	Attestation claim
signature	string	Yes	Ed25519 signature

Request

curl -X POST https://isnad.site/api/v1/attest \
  -H "X-API-Key: isnad_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": "agent-a", "witness": "agent-b", "claim": "reliable", "signature": "base64..."}'

Response

{
  "attestation_id": "att_9f3a...",
  "subject": "agent-a",
  "witness": "agent-b",
  "recorded": true
}

Rate Limits

Default rate limit: 60 requests/minute per IP, with a burst allowance of 10 requests.

Free tier API keys currently get 50 calls/month. API key holders also receive their configured per-minute limit (default: 100 req/min).

When rate-limited, the API returns 429 Too Many Requests. Implement exponential backoff in your client.

SDKs & Examples

import requests

# Trust check
resp = requests.get("https://isnad.site/api/v1/check/gpt-4-assistant")
data = resp.json()
print(f"Score: {data['overall_score']}, Certified: {data['certified']}")

# Admin-only key issuance
resp = requests.post(
    "https://isnad.site/api/v1/keys",
    headers={"X-Admin-Key": "YOUR_ADMIN_KEY"},
    json={"owner_email": "you@example.com"}
)
api_key = resp.json()["api_key"]

# Submit attestation (authenticated)
requests.post(
    "https://isnad.site/api/v1/attest",
    headers={"X-API-Key": api_key},
    json={
        "subject": "agent-a",
        "witness": "agent-b",
        "claim": "reliable",
        "signature": "base64..."
    }
)