> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Risk Classification

> EU AI Act risk levels for AI agents - classify, track, and govern

The EU AI Act requires organizations to classify AI systems by risk level. MeshAI supports four risk levels and provides AI-assisted suggestions to help you classify each agent.

## Risk Levels

| Level            | Description                                                         | Obligations                                                            |
| ---------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Minimal**      | Low-risk agents (spam filters, recommendations)                     | Basic monitoring only                                                  |
| **Limited**      | Agents interacting with humans (chatbots, content generators)       | Transparency obligations - users must know they're interacting with AI |
| **High**         | Agents in critical domains (HR, finance, healthcare)                | Full compliance: audit trail, HITL, FRIA, human oversight              |
| **Unacceptable** | Banned use cases (social scoring, real-time biometric surveillance) | Should not be deployed without safeguards and exemptions               |

## Classify an Agent

Classification is an upsert: an agent has at most one classification on record, and classifying it again replaces the previous risk level and justification (the earlier record is not versioned).

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.meshai.dev/api/v1/agents/01ARZ3NDEKTSV4RRFFQ69G5FAV/risk-classification \
    -H "Authorization: Bearer msh_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "risk_level": "high",
      "justification": "Agent processes employee performance data for HR decisions",
      "assessed_by": "user@company.com",
      "domain_tags": ["hr", "employment"],
      "ai_act_categories": ["Annex III(4) - employment, workers management"]
    }'
  ```

  ```python SDK theme={null}
  from meshai import MeshAI

  client = MeshAI(api_key="msh_...")

  classification = client.classify_risk(
      agent_id="01ARZ3NDEKTSV4RRFFQ69G5FAV",
      risk_level="high",
      justification="Agent processes employee performance data for HR decisions",
      assessed_by="user@company.com",
      domain_tags=["hr", "employment"],
      ai_act_categories=["Annex III(4) - employment, workers management"],
  )
  ```
</CodeGroup>

`assessed_by` is required (1–100 characters); `domain_tags` and `ai_act_categories` are optional free-form lists you use to tag the agent's domain and the Annex III categories it falls under.

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": 9,
      "agent_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "risk_level": "high",
      "justification": "Agent processes employee performance data for HR decisions",
      "assessed_by": "user@company.com (key:a1b2c3d4)",
      "review_date": "2026-03-17T10:00:00Z",
      "domain_tags": ["hr", "employment"],
      "ai_act_categories": ["Annex III(4) - employment, workers management"],
      "created_at": "2026-03-17T10:00:00Z",
      "updated_at": "2026-03-17T10:00:00Z"
    }
  }
  ```
</ResponseExample>

`assessed_by` is bound to the authenticated API key (a `(key:...)` suffix is appended) to prevent identity spoofing.

## AI-Assisted Suggestion

Not sure which level to assign? Use the suggestion endpoint. MeshAI analyzes the agent's metadata (environment, framework, model provider, and metadata flags like `handles_pii`) and suggests a risk level.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.meshai.dev/api/v1/agents/01ARZ3NDEKTSV4RRFFQ69G5FAV/risk-suggestion \
    -H "Authorization: Bearer msh_YOUR_API_KEY"
  ```

  ```python SDK theme={null}
  suggestion = client.suggest_risk_classification("01ARZ3NDEKTSV4RRFFQ69G5FAV")
  # Returns: {"suggested_level": "high", "confidence": 0.85, "reasoning": "...", "factors": [...]}
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "suggested_level": "high",
      "confidence": 0.85,
      "reasoning": "Score 0.85 based on: Runs in production environment; Uses external model provider: openai; Handles PII data",
      "factors": [
        "Runs in production environment",
        "Uses external model provider: openai",
        "Handles PII data"
      ]
    }
  }
  ```
</ResponseExample>

<Warning>
  AI suggestions are advisory only. A human must review and confirm the final classification. The suggestion is not recorded as the official classification until you call the classify endpoint.
</Warning>

## Get Current Classification

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.meshai.dev/api/v1/agents/01ARZ3NDEKTSV4RRFFQ69G5FAV/risk-classification \
    -H "Authorization: Bearer msh_YOUR_API_KEY"
  ```

  ```python SDK theme={null}
  classification = client.get_risk_classification("01ARZ3NDEKTSV4RRFFQ69G5FAV")
  ```
</CodeGroup>

## List Classifications

Optionally filter by `risk_level`:

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.meshai.dev/api/v1/risk-classifications?risk_level=high&page=1&limit=50" \
    -H "Authorization: Bearer msh_YOUR_API_KEY"
  ```

  ```python SDK theme={null}
  classifications = client.list_risk_classifications(risk_level="high")
  ```
</CodeGroup>

## Bulk Classify

Classify up to 100 agents in a single request:

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.meshai.dev/api/v1/risk-classifications/bulk \
    -H "Authorization: Bearer msh_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "classifications": [
        {
          "agent_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
          "risk_level": "high",
          "justification": "Processes HR data",
          "assessed_by": "user@company.com"
        },
        {
          "agent_id": "01BX5ZZKBKACTAV9WEVGEMMVRZ",
          "risk_level": "limited",
          "justification": "Customer-facing chatbot",
          "assessed_by": "user@company.com"
        }
      ]
    }'
  ```

  ```python SDK theme={null}
  result = client.classify_agents_bulk([
      {"agent_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV", "risk_level": "high", "justification": "Processes HR data", "assessed_by": "user@company.com"},
      {"agent_id": "01BX5ZZKBKACTAV9WEVGEMMVRZ", "risk_level": "limited", "justification": "Customer-facing chatbot", "assessed_by": "user@company.com"},
  ])
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": { "created": 1, "updated": 1, "failed": 0 }
  }
  ```
</ResponseExample>

## Suggest for All Agents

Get risk suggestions for every agent in your tenant (classified and unclassified) in one call:

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.meshai.dev/api/v1/risk-classifications/suggest-all \
    -H "Authorization: Bearer msh_YOUR_API_KEY"
  ```

  ```python SDK theme={null}
  suggestions = client.suggest_risk_all()
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "suggestions": [
        {
          "agent_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
          "suggested_level": "high",
          "confidence": 0.85,
          "reasoning": "Score 0.85 based on: Runs in production environment; Handles PII data",
          "factors": ["Runs in production environment", "Handles PII data"]
        }
      ]
    }
  }
  ```
</ResponseExample>

## What Changes by Risk Level

| Capability         | Minimal  | Limited  | High     | Unacceptable |
| ------------------ | -------- | -------- | -------- | ------------ |
| Basic monitoring   | Yes      | Yes      | Yes      | Yes          |
| Transparency card  | Optional | Required | Required | Required     |
| Audit trail        | Basic    | Full     | Full     | Full         |
| HITL approval      | Optional | Optional | Required | Required     |
| FRIA               | No       | No       | Required | Required     |
| Incident reporting | No       | No       | Required | Required     |
| Human oversight    | No       | Optional | Required | Required     |