Reputation

Query agent reputation scores, browse score history, submit attestations, and verify score integrity.

Overview

The Reputation API exposes an agent's trust score, its history over time, and a cryptographic verification mechanism. Scores are computed from action volume, mutual-sign completion rate, dispute rate, verifiable-credential validity, and account age. Two endpoints are public (rate-limited, no auth required); the remaining two require a Bearer token.

Get Reputation Score

GET /api/v1/agents/{agent_slug}/reputation

Returns the current reputation score for an agent. Public endpoint — no authentication required (rate-limited).

Example Response

{
  "agent_id": "a1b2c3d4-...",
  "score": 82,
  "tier": "trusted",
  "component_scores": {
    "action_volume": 90.0,
    "mutual_sign_completion_rate": 85.0,
    "dispute_rate": 95.0,
    "vc_validity": 70.0,
    "account_age": 60.0
  },
  "computed_at": "2026-06-04T14:22:00Z",
  "action_count": 314,
  "mutual_sign_completion_rate": 0.92,
  "dispute_rate": 0.03,
  "score_hash": "sha256:ab12cd..."
}

Response Fields

Field	Type	Description
`agent_id`	string	UUID of the agent
`score`	integer	Overall reputation score (0-100)
`tier`	string	Human-readable trust tier derived from the score
`component_scores`	object	Per-component breakdown (each 0-100)
`computed_at`	string	When the score was last computed (ISO 8601 UTC)
`action_count`	integer	Total actions evaluated
`mutual_sign_completion_rate`	float	Fraction of actions completed with mutual signatures
`dispute_rate`	float	Fraction of actions that resulted in disputes
`score_hash`	string	SHA-256 hash for independent verification

Component Scores

Component	Description
`action_volume`	Score based on the total number of recorded actions
`mutual_sign_completion_rate`	Score based on actions completed with both parties signing
`dispute_rate`	Score inversely related to the proportion of disputed actions
`vc_validity`	Score based on verifiable credential validity checks
`account_age`	Score based on how long the agent has been registered

If the agent exists but no reputation score has been computed yet, the endpoint returns 404 Not Found.

Get Reputation History

GET /api/v1/agents/{agent_slug}/reputation/history
Authorization: Bearer aira_live_xxxxx

Returns the full reputation score history for an agent. Requires authentication — the agent must belong to the caller's organization.

Example Response

{
  "agent_id": "a1b2c3d4-...",
  "history": [
    {
      "score": 82,
      "tier": "trusted",
      "component_scores": {
        "action_volume": 90.0,
        "mutual_sign_completion_rate": 85.0,
        "dispute_rate": 95.0,
        "vc_validity": 70.0,
        "account_age": 60.0
      },
      "computed_at": "2026-06-04T14:22:00Z",
      "action_count": 314,
      "mutual_sign_completion_rate": 0.92,
      "dispute_rate": 0.03,
      "score_hash": "sha256:ab12cd..."
    },
    {
      "score": 78,
      "tier": "trusted",
      "component_scores": {
        "action_volume": 85.0,
        "mutual_sign_completion_rate": 80.0,
        "dispute_rate": 90.0,
        "vc_validity": 70.0,
        "account_age": 55.0
      },
      "computed_at": "2026-06-03T14:22:00Z",
      "action_count": 290,
      "mutual_sign_completion_rate": 0.89,
      "dispute_rate": 0.04,
      "score_hash": "sha256:ef34gh..."
    }
  ],
  "request_id": "req_01J8X..."
}

History Item Fields

Field	Type	Description
`score`	integer	Reputation score at that point in time
`tier`	string	Trust tier at that point in time
`component_scores`	object	Per-component breakdown
`computed_at`	string	When this score was computed (ISO 8601 UTC)
`action_count`	integer	Total actions evaluated at that point
`mutual_sign_completion_rate`	float	Mutual-sign completion rate at that point
`dispute_rate`	float	Dispute rate at that point
`score_hash`	string	SHA-256 hash of the score snapshot

Submit Attestation

POST /api/v1/agents/{agent_slug}/reputation/attest
Authorization: Bearer aira_live_xxxxx
Content-Type: application/json

Submit a counterparty attestation for an agent. The attestation is cryptographically verified against the counterparty's DID public key (Ed25519) before being recorded. Requires authentication.

Request Body

{
  "counterparty_did": "did:web:example.com",
  "action_uuid": "act_01J8X...",
  "attestation": "positive",
  "signature": "z3hQ9..."
}

Request Fields

Field	Type	Required	Description
`counterparty_did`	string	Yes	DID of the attesting counterparty (must match `did:web:*`)
`action_uuid`	string	Yes	UUID of the action being attested
`attestation`	string	Yes	`positive` or `negative`
`signature`	string	Yes	Ed25519 signature over the attestation payload (base58-encoded, optional `z` multibase prefix)

The signature is verified over a JSON payload containing agent_slug, action_uuid, attestation, and counterparty_did (sorted keys). The counterparty's DID public key must be registered in Aira.

Example Response (accepted)

{
  "accepted": true,
  "message": "Attestation recorded: positive",
  "request_id": "req_01J8X..."
}

Example Response (rejected)

{
  "accepted": false,
  "message": "Signature verification failed",
  "request_id": "req_01J8X..."
}

Response Fields

Field	Type	Description
`accepted`	boolean	Whether the attestation was recorded
`message`	string	Human-readable result or rejection reason
`request_id`	string	Request tracking ID

Verify Reputation Score

GET /api/v1/agents/{agent_slug}/reputation/verify

Verify a reputation score hash independently. Returns the score, its hash, and all inputs used to compute it so anyone can recompute and confirm integrity. Public endpoint — no authentication required (rate-limited).

Example Response

{
  "agent_id": "a1b2c3d4-...",
  "score": 82,
  "score_hash": "sha256:ab12cd...",
  "computed_at": "2026-06-04T14:22:00Z",
  "component_scores": {
    "action_volume": 90.0,
    "mutual_sign_completion_rate": 85.0,
    "dispute_rate": 95.0,
    "vc_validity": 70.0,
    "account_age": 60.0
  },
  "verification_inputs": {
    "score": 82,
    "component_scores": {
      "action_volume": 90.0,
      "mutual_sign_completion_rate": 85.0,
      "dispute_rate": 95.0,
      "vc_validity": 70.0,
      "account_age": 60.0
    },
    "computed_at": "2026-06-04T14:22:00",
    "hash_matches": true
  }
}

Response Fields

Field	Type	Description
`agent_id`	string	UUID of the agent
`score`	integer	The reputation score
`score_hash`	string	SHA-256 hash stored with the score
`computed_at`	string	When the score was computed (ISO 8601 UTC)
`component_scores`	object	Per-component breakdown used in hash computation
`verification_inputs`	object	All inputs used to produce the hash, plus `hash_matches` boolean

The verification_inputs.hash_matches field is true when the recomputed hash matches the stored score_hash, confirming score integrity.

Reputation

On this page