Agent Seal API Guide

Developer API

Agent accountability over HTTPS.

Use the Agent Seal API to discover the registry, verify signed Agent Cards, register agents, inspect public standing, export court evidence, append signed events, and retrieve EU AI Act readiness evidence.

Register an agent View endpoints Open verifier Registration schema

Base URL

https://agent-seal.xyz

Public read endpoints are anonymous. Writes are accepted only as signed event intents from the agent or liability anchor. Use Accept: application/json unless the endpoint returns SVG, HTML, or plain text.

Quickstart

1. Discover the registry

Fetch the signed Agent Card, JWKS, accountability profile, and registration schema before making assumptions about available routes.

2. Verify an agent

Read public status, then verify the manifest hash, keeper, public key, standing, seal URLs, and optional court export.

3. Append signed changes

Change version, name, capabilities, compliance metadata, anchor, or revocation status by posting signed events. The registry only verifies and appends.

API conventions

  • List endpoints use limit and offset.
  • Paginated responses return data and pagination.nextOffset.
  • Errors return JSON with an error field.
  • Rate-limited requests return 429 and Retry-After.
  • EU AI Act outputs are readiness aids, not legal advice or compliance verdicts.
First requests Profile 
curl -sS https://agent-seal.xyz/.well-known/agent-card.json
curl -sS https://agent-seal.xyz/.well-known/jwks.json
curl -sS "https://agent-seal.xyz/v1/public/agents?limit=10"

Register an agent

Four ways to seal an agent identity — pick whichever fits your stack. All options generate an Ed25519 keypair locally on first run; the private key never leaves your machine. Registered agents appear immediately in the public verifier.

Python SDK

agent-seal-xyz

pip install agent-seal-xyz 
from agent_seal_xyz import seal

agent = seal(
    name="my-agent",
    architect="you@email.com",
    capabilities=["code-review"],
    model="claude-sonnet-4-6",
)
print(agent.sijil, agent.seal_url)
PyPI → Source →

Python CLI

agent-seal CLI

pip install agent-seal-xyz 
# Register
agent-seal register \
  --name my-agent \
  --architect you@email.com \
  --capabilities code-review,pr-analysis

# Check status
agent-seal status <agent-id>

# Verify seal
agent-seal verify <agent-id>
PyPI →

JavaScript / TypeScript

agent-seal-xyz

npm install agent-seal-xyz 
import { seal } from 'agent-seal-xyz'

const agent = await seal({
  name: 'my-agent',
  architect: 'you@email.com',
  capabilities: ['code-review'],
  model: 'claude-sonnet-4-6',
  // reuse identity: privateKey: process.env.AGENT_KEY
})
console.log(agent.sijil, agent.sealUrl)
npm → Source →

GitHub Actions

agent-seal/register-action

agent-seal/register-action@v1 
- uses: agent-seal/register-action@v1
  with:
    name: my-agent
    architect: ${{ secrets.AGENT_SEAL_ARCHITECT_EMAIL }}
    capabilities: code-review,pr-analysis
    model: claude-sonnet-4-6
    # stable identity across runs:
    private-key: ${{ secrets.AGENT_SEAL_PRIVATE_KEY }}
Source →

Key management

  • First run generates an Ed25519 keypair at ~/.agent-seal/keys/.
  • Private key never leaves your machine — registry only ever sees the public key and signatures.
  • Re-use a stable identity: pass private_key= (Python), privateKey: (JS), or private-key: (Action).
  • Store the private key hex in an env var or CI secret for persistent identities across runs.

After registration

  • Agent gets a Sijil number and a signed covenant.
  • Public seal SVG at /v1/agents/<id>/seal.svg.
  • Verifiable at agent-seal.xyz/verifier immediately.
  • Badge embeddable in README: /v1/agents/<id>/badge.svg.
  • Full event history at /v1/agents/<id>/events.

Depth Covenant — Aix-Route

Past its reasoning horizon, an LLM does not slow down — it hallucinates confidently. Aix-Route is the open-source router behind the Depth Covenant: it measures a model's Deterministic Horizon d* and delegates to a tool before the cliff. Same math in Python and TypeScript, calibrate it on your own endpoints. Try it live at agent-seal.xyz/depth.

Python

aix-route

pip install aix-route 
from deterministic_horizon import (
    should_delegate, recommend_model,
)

# delegate before the horizon
should_delegate(estimated_depth=35, model="gpt-4o")   # True
should_delegate(estimated_depth=12, model="gpt-4o")   # False

# pick the least over-powered model for a depth
recommend_model(estimated_depth=18)
PyPI → Source →

JavaScript / TypeScript

aix-route

npm install aix-route 
import { shouldDelegate, shouldDelegateBatch } from 'aix-route'

// one decision
shouldDelegate(35, 'gpt-4o')            // true

// plan a whole decomposition at once
shouldDelegateBatch([5, 8, 35], 'gpt-4o')
// → [false, false, true]
npm → Source →

Calibrate your own model

  • Surveyed horizons run high; served endpoints run lower — measure, don't assume.
  • Python CLI: aix-route calibrate --model llama-3.3-70b-versatile --depths 3,5,8,10,12,15 --n 10
  • Needs a provider key (GROQ_API_KEY) or local ollama serve.
  • Out-of-regime fits are rejected, never faked — it falls back to an empirical crossing depth.
Runtime delegation over HTTPS Live demo 
curl -sS -X POST https://agent-seal.xyz/api/depth/delegate \
  -H "Content-Type: application/json" \
  -d '{ "task": "Sort [5,2,8,1,3] using adjacent swaps",
        "model": "llama-3.3-70b-versatile" }'

# → { "depth": 10, "dStar": 8.2,
#     "delegate": true, "reason": "above_horizon" }

Authentication

Public reads

Discovery, public registry status, seal verification, court exports, leaderboards, GPAI pointers, and compliance templates are public. They are designed for browsers, auditors, and other agents.

Signed writes

Registration uses proof of key possession. Later updates use Ed25519 signatures over canonical event intents. Operator write routes have been removed and return 410 Gone.

Signed event intent agent signature 
{
  "eventId": "evt_2026_0001",
  "eventType": "agent:update-version",
  "previousEventHash": null,
  "createdAt": "2026-06-10T00:00:00.000Z",
  "payload": { "version": "1.1.0" },
  "signerType": "agent",
  "signature": "128-hex-character-ed25519-signature"
}

Endpoint Reference

Discovery and signed identity

MethodPathPurpose
PAGE/verifierPublic browser verifier for signed cards, JWKS, status, EU evidence, court export, event history, and PEDIGREE intent-chain records.
PAGE/registerPlain-language registration guide for non-technical operators, founders, and developer handoff.
PAGE/case-studiesPlain-language pilot patterns with static evidence examples.
PAGE/researchWorking papers: the repository research paper and the standards evidence-layer position paper.
GET/agent-registration.jsonMachine-readable registration flow and payload requirements.
GET/.well-known/agent-card.jsonSigned A2A Agent Card and public registry skills.
GET/.well-known/jwks.jsonPublic keys used to verify registry card signatures.
GET/.well-known/agent-accountability-profile.jsonVendor-neutral evidence profile for autonomous-agent accountability.
GET/agent-manifest.txtPlain-text manifest with key public endpoints.
GET/llms.txtAI-readable index of registry entry points.

Public registry reads

MethodPathPurpose
GET/v1/statsLive registry counts used by the landing page.
GET/v1/public/agents?limit=100&offset=0Paginated public list of registered agents.
GET/v1/public/leaderboard?limit=10Public trust leaderboard with deterministic score breakdowns.
GET/v1/public/agents/{agent_id}/statusPublic status, keeper, key, manifest hash, and seal links for one agent.
GET/v1/agents/{agent_id_or_did}/cardRegistry-issued signed A2A Agent Card for one agent. DID form is did:aip:agent:<base64url(agent_id)>.
POST/v1/agents/{agent_id_or_did}/verifyVerify a supplied or registry-issued card against registry keys, with optional requirePq.
GET/v1/agents/{agent_id}/stateCurrent state derived by replaying signed events over immutable registration.
GET/v1/agents/{agent_id}/eventsFull append-only event history with event hashes and previous-event links.
GET/v1/seal/verify?hash={manifest_hash}&agent={agent_id}Verify a scanned or linked seal payload.
GET/v1/agents/{agent_id}/seal.svgFull SVG evidence seal with visible facts, embedded metadata, and QR evidence manifest.
GET/v1/agents/{agent_id}/badge.svgCompact embeddable verification badge.

Depth Covenant

MethodPathPurpose
PAGE/depthLive client-side demo: enter a task, watch the bar decide delegate vs. reason against the calibrated horizon.
POST/api/depth/delegateEstimate reasoning depth for a task and return { depth, dStar, delegate, reason } for a given model.

Evidence and EU AI Act readiness

MethodPathPurpose
GET/v1/public/agents/{agent_id}/court-exportRedacted public court export with trace DAG, visible trace records, and court summary.
GET/v1/public/agents/{agent_id}/eu-ai-act-readinessArticle-mapped readiness matrix for one agent.
GET/v1/public/agents/{agent_id}/eu-ai-act-evidenceMachine-readable EU AI Act evidence bundle with redaction policy, timestamp receipt summaries, and incident/complaint references.
GET/v1/public/evidence-redaction-policyPublic evidence policy: hashes, roots, statuses, counts, and procedure references are exposed; private reports and raw proof payloads are not.
GET/v1/public/agents/{agent_id}/eu-compliance-reportHuman-readable agent-level evidence report.
GET/v1/public/eu-databaseEU-database-style public feed. Not the official EU database.
GET/v1/public/gpai-modelsPublic GPAI documentation pointers for model transparency, copyright, and safety materials.
GET/v1/public/compliance/templatesWhitelisted compliance template index.
GET/v1/public/compliance/templates/{slug}.mdDownload a readiness template such as FRIA, QMS, checklist, or roadmap.
GET/examples/aisthetix-eu-ai-act-evidence-v0.1.jsonFrozen public sample evidence bundle used by the verifier demo mode.
GET/examples/support-disclosure-agent-evidence-v0.1.jsonStatic low-risk transparency case-study evidence sample.
GET/examples/benefits-triage-agent-evidence-v0.1.jsonStatic Annex III-style case-study evidence sample.

Registration and signed events

MethodPathPurpose
POST/v1/agents/challengeIssue a short-lived challenge for proof of key possession.
POST/v1/agents/registerRegister an immutable sealed covenant with proof of key possession and liability-anchor legal terms.
POST/v1/agents/{agent_id}/eventsAppend a signed event such as version, capabilities, compliance metadata, anchor transfer, or revocation.
Legal boundary: EU AI Act endpoints provide technical evidence and readiness mapping. They do not replace legal assessment, conformity assessment, FRIA ownership, official EU database registration, or qualified counsel review.