Developers · API Reference

Action Assessment API v1

One endpoint, one request schema, one response schema. Assessments are deterministic for the same input and engine version, and Asyrx never authorizes, executes or blocks the action it assesses.

Endpoint

POST https://asyrx.com/api/v1/actions/assess

Authentication

Bearer authentication with an organization-scoped API key. Keys are issued through an approval process; there is no public self-service signup.

Headers

Authorization: Bearer <api_key>
Content-Type: application/json
Idempotency-Key: <optional, unique per logical request>

Keys carry scopes. A key without the assess scope receives 403 INSUFFICIENT_SCOPE.
Keys are bound to an environment mode. Test keys produce test-mode assessments; live keys produce live assessments, and the mode is echoed as environment_mode.
Keys are server-side credentials. Never embed one in a browser, mobile app or public repository.

Request body

JSON only. Unknown fields are rejected rather than silently ignored, so a typo never becomes a missing signal.

Field	Type	Requirement	Description
action_type	string	Required	Provider-native or generic action identifier, e.g. crm.records.export. Normalized before scoring; max 160 characters.
environment	enum	Required	Which environment the action would run in. One of production, staging, sandbox, development.
agent_id	string	Optional	Your identifier for the agent proposing the action. Used for behavioural context; max 120 characters.
target_system	string	Optional	System of record the action targets, e.g. salesforce, shopify, github.
target_resource	string	Optional	Object or resource the action targets, e.g. Contact, Order, repository.
action_description	string	Optional	Human-readable description of the proposed action; max 2,000 characters.
entities_affected	integer	Optional	Number of distinct entities in scope. Drives the entity impact dimension.
records_affected	integer	Optional	Number of records in scope. Drives volume risk factors.
financial_value	number	Optional	Monetary exposure of the action, in the supplied currency.
currency	string	Optional	Three-letter ISO currency code, required for meaningful financial context.
destination	string	Optional	Where data or value would go. Novel destinations raise a risk factor.
data_classification	enum	Optional	Sensitivity of data in scope: public, internal, confidential, restricted, regulated, unknown.
reversibility	enum	Optional	How recoverable the action is, from fully_reversible to irreversible.
privilege_change	boolean	Optional	True when the action changes permissions, roles or credentials.
production_impact	boolean	Optional	True when live operational dependencies are affected.
metadata	object	Optional	Your own structured context, echoed into the assessment record.
context	object	Optional	Additional workflow context such as workflow_id or requested_by.

Example request

{
  "agent_id": "agt_customer_operations_01",
  "target_system": "salesforce",
  "action_type": "crm.records.export",
  "environment": "production",
  "records_affected": 84000,
  "entities_affected": 84000,
  "data_classification": "confidential",
  "destination": "external_analytics",
  "reversibility": "partially_reversible"
}

Enumerations

Values outside these sets are rejected with a validation error.

environment

production · staging · sandbox · development

data_classification

public · internal · confidential · restricted · regulated · unknown

reversibility

fully_reversible · mostly_reversible · partially_reversible · difficult_to_reverse · irreversible · unknown

Response body

A 200 response is a completed assessment. Scores are 0–100; levels are minimal, low, moderate, high and critical.

Field	Meaning
assessment_id / action_id	Stable identifiers for the stored assessment and the proposed action.
request_id	Trace identifier, also returned in the asyrx-request-id header.
status	completed when a full assessment was produced.
api_version / risk_engine_version / policy_version	The contract, engine and policy versions that produced this result.
normalized_action_type / action_category	The canonical action type Asyrx scored, and its category (data, financial, access, infrastructure, communication, other).
action_risk	score 0–100, level, and confidence 0–1 for the action itself.
blast_radius	score 0–100, level, and six dimensions: financial_impact, entity_impact, data_impact, operational_impact, privilege_impact, reversibility.
risk_factors[]	Explanatory factors, each with code, category, severity and a human-readable message.
recommended_control	The single strongest recommendation: type, priority and the because reasons behind it.
recommendations[]	All applicable recommendation codes, e.g. VERIFY_DESTINATION, VERIFY_SCOPE.
behavioral_context	Whether a baseline existed for this organization, its sample size and window, and volume/velocity multipliers.
policy_context[]	Customer policy rules that matched, with the policy, rule and effect.
summary	One-paragraph natural-language explanation of the assessment.
processing_time_ms / created_at	Server-side processing time and the assessment timestamp.
disclaimer	Asyrx returns intelligence only; the customer remains responsible for authorization and execution.

200 OK

{
  "api_version": "v1",
  "risk_engine_version": "1.0",
  "policy_version": "1.0",
  "assessment_id": "1f3c9b7a-6d24-4a8e-9c51-77b0f2a4e1d9",
  "action_id": "8b2e5d41-90c7-4f6a-b3ae-0c19d7f45a62",
  "request_id": "req_01j9x8k2j3n4m5p6q7r8s9t0u1",
  "status": "completed",
  "environment_mode": "test",
  "normalized_action_type": "crm.records.export",
  "action_category": "data",
  "action_risk": { "score": 60, "level": "moderate", "confidence": 0.77 },
  "blast_radius": {
    "score": 97,
    "level": "critical",
    "dimensions": {
      "financial_impact": 0,
      "entity_impact": 95,
      "data_impact": 97,
      "operational_impact": 45,
      "privilege_impact": 0,
      "reversibility": 48
    }
  },
  "risk_factors": [
    {
      "code": "NOVEL_DESTINATION",
      "category": "destination",
      "severity": "high",
      "message": "Destination \"external_analytics\" has not been used by this organization before."
    },
    {
      "code": "HIGH_ENTITY_COUNT",
      "category": "volume",
      "severity": "critical",
      "message": "84,000 records in scope for a single action."
    },
    {
      "code": "SENSITIVE_DATA_EXPORT",
      "category": "data",
      "severity": "critical",
      "message": "84,000 confidential records would leave the system of record."
    },
    {
      "code": "PRODUCTION_ENVIRONMENT",
      "category": "environment",
      "severity": "moderate",
      "message": "The action targets a live production environment."
    }
  ],
  "recommended_control": {
    "type": "SECONDARY_APPROVAL_RECOMMENDED",
    "priority": "critical",
    "because": ["Novel destination", "High entity count", "Sensitive data export"]
  },
  "recommendations": ["VERIFY_DESTINATION", "VERIFY_SCOPE", "CONFIRM_PRODUCTION_ENVIRONMENT"],
  "behavioral_context": {
    "historical_comparison_available": false,
    "baseline_scope": "organization",
    "sample_size": 0,
    "window_days": 30,
    "entity_volume_multiplier": null,
    "financial_value_multiplier": null,
    "velocity_multiplier": null,
    "destination_seen_before": false,
    "action_type_seen_before": false
  },
  "policy_context": [],
  "summary": "Action Risk 60 with a Blast Radius of 97. Primary drivers: novel destination and high entity count. Secondary Approval Recommended. Asyrx does not authorize, execute or block this action.",
  "processing_time_ms": 41,
  "created_at": "2026-09-01T16:12:04.118Z",
  "disclaimer": "Asyrx provides risk intelligence and decision-support recommendations for proposed AI-agent actions. Customers remain responsible for authorization, execution and final operational decisions."
}

Scores are produced by the Asyrx risk engine. The inputs and the resulting factors are fully disclosed above; the internal weighting is proprietary and is not exposed through the API.

Response headers

Present on both success and error responses.

Header	Meaning
asyrx-request-id	Trace identifier for this request.
asyrx-api-version	API version that served the request (v1).
asyrx-ratelimit-limit	Requests permitted in the current window.
asyrx-ratelimit-remaining	Requests remaining in the current window.
asyrx-ratelimit-reset	Timestamp when the window resets.
asyrx-idempotent-replay	true when the response is a replay of an earlier identical request.
retry-after	Seconds to wait, returned with 429 responses.

Errors, idempotency and limits

Errors are informational: a rejected request means Asyrx produced no risk opinion, not that your action was blocked.

Error response

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "A field failed validation. The request was not assessed.",
    "request_id": "req_01j9x8k2j3n4m5p6q7r8s9t0u1",
    "documentation_url": "https://asyrx.com/developers/errors#validation_failed",
    "retryable": false,
    "details": [{ "field": "environment", "message": "Invalid option." }]
  },
  "request_id": "req_01j9x8k2j3n4m5p6q7r8s9t0u1",
  "disclaimer": "Asyrx provides risk intelligence and decision-support recommendations for proposed AI-agent actions. Customers remain responsible for authorization, execution and final operational decisions."
}

Maximum request body size is 64 KB; larger payloads return 413 PAYLOAD_TOO_LARGE.
Reusing an Idempotency-Key with a different body returns 409 IDEMPOTENCY_KEY_REUSED. Reusing it with the same body replays the original assessment.
Only POST is accepted; other methods return 405 METHOD_NOT_ALLOWED.

Full error catalog OpenAPI specification