Action Assessment API: one call before an agent acts

The Action Assessment API is intentionally one call. Your agent proposes an action, you POST that proposed action to a single authenticated endpoint, and you receive a structured assessment before anything executes. Everything else in the platform — behavioral baselines, policy context, review queues, webhooks, audit history — exists to make that one response better.

This walkthrough covers what to send, what comes back, and the operational behavior that matters when the call sits in a live agent pipeline: idempotency, rate limits, versioning and what to do when an assessment is unavailable.

Where the call goes in your pipeline

Place the call between the agent's decision and the write. The agent produces a proposed action; your service normalizes it into the assessment request; Asyrx returns intelligence; your policy code decides. Asyrx is not a proxy and does not sit in front of your target system, so nothing about your existing authorization path changes.

Practically, that means the integration point is your own tool-execution layer, gateway or orchestrator — wherever you already have the proposed action in structured form and still control whether it proceeds.

The request shape

A request describes what the action would do, not how your code would do it. The endpoint accepts a target system, an action type, and structured action context: entity counts, monetary amounts, data classifications, destinations, privilege changes and identifiers for the agent and its principal.

Because the contract is provider-agnostic, Salesforce, Shopify and GitHub are documented reference scenarios rather than a closed list. Any system is described through the same structured action metadata, which is what allows one set of thresholds to cover several integrations.

• Agent and principal identifiers, so behavioral baselines can be built per agent
• Target system and action type, normalized into an action category
• Scope: how many entities, which objects, which environment
• Exposure: monetary amounts and data classifications where they apply
• Destination: where data would go, if the action moves data
• Idempotency-Key header on any call you might retry

The response contract

Every assessment returns an Action Risk Score, a Blast Radius Score and a risk level for each, a confidence value, blast radius dimensions with rationales, risk factors, machine-readable reason codes, and recommended controls. Reason codes explain the score; recommended controls describe what a cautious operator would do — request human review, verify a destination, reduce scope — without ever making the decision for you.

Scores use published bands, so a threshold configured against one integration means the same thing in another. Version identifiers for the risk engine and the active policy are returned alongside the scores, which is what makes a historical assessment reproducible during an audit.

Treat reason codes as the contract

Reason codes are the stable surface. Human-readable labels can be reworded for clarity, but codes are additive and safe to build logic against. If you find yourself string-matching a risk factor label in policy code, switch to the code — it will survive copy changes and locale differences.

Operational guarantees

Writes accept an Idempotency-Key header, so a retried call replays the original assessment instead of creating a second one. Rate limit headers are returned on every response, and endpoints are path-versioned with additive, backward-compatible fields.

If a dependency is unavailable, the API returns ASSESSMENT_UNAVAILABLE (503) rather than guessing. That is never an authorization signal: the action was neither approved nor blocked, and your systems decide how to proceed. Deciding that fallback explicitly — proceed, queue, or escalate, per action category — is the single most important design choice in the integration.

• Bearer authentication with environment-scoped, hashed, revocable keys
• Path-versioned endpoints with additive, backward-compatible fields
• HMAC-SHA256 signed webhooks with exponential backoff on retry
• A published OpenAPI 3.1 contract behind every documented endpoint

Errors, rate limits and versioning in practice

The error catalog is small on purpose, and each entry maps to a distinct developer action rather than a generic retry. Validation failures describe which field of the action context was rejected, authentication failures distinguish a missing credential from a revoked one, and rate limiting returns the headers your client needs to back off without guessing. None of these are risk signals, and none of them should ever be interpreted as an approval or a denial.

Versioning is path-based, and field additions are additive. In practice that means a client should parse defensively: read the fields you use, ignore fields you do not recognize, and never assume the reason code list is closed. New reason codes appear as the engine improves, so treat an unrecognized code as an unknown contributing signal and fall back to the score and level you already understand.

• Read rate limit headers on every response instead of inferring limits from failures
• Retry only what is safe to retry, always with an Idempotency-Key
• Parse additively — unknown fields and unknown reason codes are expected over time
• Store the engine and policy versions with each assessment so results stay reproducible

Testing the integration honestly

The most useful test suite is not a set of happy-path fixtures. Build cases for the edges that will actually hurt: an action with a first-seen destination, an action far above the agent's normal volume, an action with low confidence because history is thin, a 503 from the assessment endpoint, and a duplicated webhook delivery.

Run those cases against sandbox credentials with the Action Simulator, and assert on your own routing behavior rather than on exact score values. Scores evolve as the engine improves; your routing rules are the thing you own and the thing that must stay correct.

Webhooks and asynchronous review

Some actions should not resolve inside the request. When a recommended control routes an action to human review, the review outcome arrives as a signed webhook, so your service can resume or abandon the action without polling.

Verify the HMAC-SHA256 signature before parsing any payload, and make handlers idempotent — retries with exponential backoff mean a handler will occasionally see the same event twice.

What Asyrx will never do in your pipeline

The API does not authorize, approve, deny, block or execute the action. It returns intelligence about a proposed action, and your application remains the only component that can decide and act. That constraint is what allows the call to be added to a production agent pipeline without redesigning authorization, and what makes the failure mode of the service a known quantity rather than an outage in your write path.