assess

The core call. Runs the four check trust stack against an agent and an intended action, and returns a decision your agent can act on and present to its counterparty.

POST/v1/assess

Authentication

Requires Authorization: Bearer <key> (an af_live_… /af_test_… key). Unauthenticated calls return 401; each key is rate limited per minute (429 when exceeded).

Request body

JSON. Fields marked * are required.

Field	Type	Description
agent*	string	The agent to assess, an A2A agent card URL or a known AgentFide agent id.
acting_for	object	Who the agent acts for, and under what mandate.
action*	object	The intended action (see below).
context	object	Marketplace + idempotency metadata.

acting_for

Field	Type	Description
principal*	string	Identifier of the principal the agent acts for.
mandate	object	Scoped authority: id, scope, limit, currency, expires_at.

action

Field	Type	Description
type*	enum	pay · purchase · hire · transfer · other
amount	number	Transaction amount.
currency	string(3)	ISO-4217 currency code.
counterparty	string	Identifier of the counterparty.
description	string	Free-text description of the action.

context

Field	Type	Description
marketplace	string	Marketplace the action originates from.
idempotency_key	string	Repeat calls with the same key return the same assessment.

Example request

POST /v1/assess

{
  "agent": "https://seller.example/.well-known/agent-card.json",
  "acting_for": {
    "principal": "acct_42",
    "mandate": { "limit": 500, "currency": "USD", "expires_at": "2026-12-31T00:00:00Z" }
  },
  "action": {
    "type": "purchase",
    "amount": 42,
    "currency": "USD",
    "counterparty": "seller_789",
    "description": "API credits"
  },
  "context": { "marketplace": "vaultplane", "idempotency_key": "ord_abc123" }
}

Response

Field	Type	Description
decision	enum	allow · review · deny
identity	object	card_verified, operator, signature_method.
authority	object	mandate_valid, in_scope, limit_remaining.
reputation	object	score (0 to 1000), tier, factors, plain language explanation.
recourse	object	available, escrow_offered, rewind_supported.
assessment_id	string	Stable id for this assessment, pass it to /v1/outcome.
expires_at	string	ISO-8601 timestamp after which the decision is stale.

200 OK

{
  "decision": "allow",
  "identity":   { "card_verified": true, "operator": "Example Corp", "signature_method": "EdDSA" },
  "authority":  { "mandate_valid": true, "in_scope": true, "limit_remaining": 458 },
  "reputation": {
    "score": 740, "tier": "gold",
    "factors": { "account_age": 180, "transaction_volume": 210, "dispute_history": 290, "in_bounds_behavior": 60 },
    "explanation": "Score 740/1000 (gold): 312 transactions over 540 days, 0.6% dispute rate, 96% of actions within mandate."
  },
  "recourse":   { "available": true, "escrow_offered": true, "rewind_supported": true },
  "assessment_id": "ass_9f2c…",
  "expires_at": "2026-06-21T17:05:00.000Z"
}

Decisions

Field	Type	Description
allow		Proceed. Identity, authority, reputation, and (where requested) recourse all clear.
review		Hold for an extra check or a human. Something is borderline.
deny		Do not proceed. A check failed, e.g. unverified card or out of scope mandate.

The four checks

Identity: the agent's signed A2A Agent Card is fetched and its signature verified. We verify the card rather than invent a credential.
Authority: the action is checked against a valid, scoped mandate (who for, what limit, expiring when). Maps to AP2 mandates.
Reputation: a transparent, explainable score from observed outcomes. An agent can never buy a better score.
Recourse: whether escrow and the Agent Rewind undo guarantee are available for this transaction.

Idempotency

Pass context.idempotency_key to make retries safe, repeat calls with the same key return the original assessment instead of creating a new one.

Errors

Field	Type	Description
400	invalid_json	Body was not valid JSON.
401	unauthorized	Missing, malformed, or invalid API key.
422	invalid_request	Body failed validation. details carries the field errors.
429	rate_limited	Per-key per-minute limit exceeded. Retry-After header included.

422 Unprocessable Entity

{
  "error": "invalid_request",
  "details": { "fieldErrors": { "action": ["Required"] } }
}

Preview behavior

Today assess performs live A2A card verification, mandate bounds checking, and a reputation score computed from reported outcomes. Recourse (escrow + Agent Rewind) is not yet offered, so decisions stay conservative. The request/response shapes are stable, see the build plan for rollout.