> ## 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.

# Governance API

> Audit trail, risk classification, policies, and approval endpoints

## Audit Trail

### List Audit Events

```
GET /audit-trail
```

| Parameter    | Type    | Description                                                  |
| ------------ | ------- | ------------------------------------------------------------ |
| `event_type` | string  | Filter by type (e.g., `agent.registered`, `policy.violated`) |
| `target_id`  | string  | Filter by target entity ID                                   |
| `from`       | string  | Start date (ISO 8601)                                        |
| `to`         | string  | End date (ISO 8601)                                          |
| `page`       | integer | Page number                                                  |
| `limit`      | integer | Results per page                                             |

```bash theme={null}
curl "https://api.meshai.dev/api/v1/audit-trail?event_type=policy.violated&limit=50" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "evt_abc123",
        "event_type": "policy.violated",
        "actor": "agt_xyz789",
        "target_id": "pol_def456",
        "target_type": "policy",
        "details": {
          "policy_name": "production-model-allowlist",
          "violation": "Model gpt-3.5-turbo is not in the allowed list"
        },
        "timestamp": "2026-03-17T10:00:00Z"
      }
    ],
    "meta": { "total": 15, "page": 1, "limit": 50 }
  }
  ```
</ResponseExample>

### Export Audit Events

```
GET /audit-trail/export
```

| Parameter    | Type   | Description           |
| ------------ | ------ | --------------------- |
| `format`     | string | `csv` or `json`       |
| `from`       | string | Start date (ISO 8601) |
| `to`         | string | End date (ISO 8601)   |
| `event_type` | string | Filter by type        |

```bash theme={null}
curl "https://api.meshai.dev/api/v1/audit-trail/export?format=csv&from=2026-01-01" \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -o audit-trail.csv
```

## Risk Classification

### Get Classification

```
GET /agents/{agent_id}/risk-classification
```

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

### Classify Agent

```
POST /agents/{agent_id}/risk-classification
```

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/agents/agt_abc123/risk-classification \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "risk_level": "high",
    "justification": "Agent processes employee performance data"
  }'
```

### Get AI Suggestion

```
GET /agents/{agent_id}/risk-suggestion
```

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

### List Risk Classifications

```
GET /risk-classifications
```

| Parameter    | Type    | Description          |
| ------------ | ------- | -------------------- |
| `risk_level` | string  | Filter by risk level |
| `page`       | integer | Page number          |
| `limit`      | integer | Results per page     |

```bash theme={null}
curl "https://api.meshai.dev/api/v1/risk-classifications?risk_level=high" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

### Bulk Classify Agents

```
POST /risk-classifications/bulk
```

Classify up to 100 agents in a single request.

```bash 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": "01HZY8K5G3QJXW7VN2P9Z6M4RT",
        "risk_level": "high",
        "justification": "Agent processes employee performance data",
        "assessed_by": "compliance@company.com"
      }
    ]
  }'
```

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

## Policies

### List Policies

```
GET /policies
```

```bash theme={null}
curl https://api.meshai.dev/api/v1/policies \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

### Create Policy

```
POST /policies
```

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/policies \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-model-allowlist",
    "policy_type": "model_allowlist",
    "config": { "allowed_models": ["gpt-4o", "claude-sonnet-4-20250514"] },
    "scope": "global",
    "enabled": true
  }'
```

Policy types: `model_allowlist`, `block_provider`, `require_approval`, `budget_limit`, `rate_limit`, `require_human_review`. See [Policies](/governance/policies) for config details.

### Get Policy

```
GET /policies/{policy_id}
```

### Update Policy

```
PATCH /policies/{policy_id}
```

```bash theme={null}
curl -X PATCH https://api.meshai.dev/api/v1/policies/pol_abc123 \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'
```

### Delete Policy

```
DELETE /policies/{policy_id}
```

```bash theme={null}
curl -X DELETE https://api.meshai.dev/api/v1/policies/pol_abc123 \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

### List Policy Templates

```
GET /policy-templates
```

Curated starter policies a tenant can add in one click. Instantiate one with the "Create Policy from Template" endpoint below.

```bash theme={null}
curl https://api.meshai.dev/api/v1/policy-templates \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

### Create Policy from Template

```
POST /policies/from-template/{template_id}
```

Instantiates a starter policy, created disabled so you can review and edit it before enabling. Both fields are optional; omitted values fall back to the template's defaults.

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/policies/from-template/approved-model-allowlist \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-model-allowlist", "priority": 200 }'
```

### Dry Run Evaluate

```
POST /policies/evaluate
```

Evaluates all applicable policies for a hypothetical request without creating a proxy request or approval. Useful for testing policy configuration before deploying an agent.

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/policies/evaluate \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "01HZY8K5G3QJXW7VN2P9Z6M4RT",
    "provider": "openai",
    "model": "gpt-4o",
    "environment": "production"
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "policy_id": 3,
        "policy_name": "production-model-allowlist",
        "policy_type": "model_allowlist",
        "result": "pass",
        "reason": null
      }
    ]
  }
  ```
</ResponseExample>

### List Policy Evaluations

```
GET /policy-evaluations
```

| Parameter   | Type    | Description            |
| ----------- | ------- | ---------------------- |
| `policy_id` | integer | Filter by policy       |
| `agent_id`  | string  | Filter by agent        |
| `result`    | string  | `pass`, `fail`, `skip` |
| `page`      | integer | Page number            |
| `limit`     | integer | Results per page       |

```bash theme={null}
curl "https://api.meshai.dev/api/v1/policy-evaluations?result=fail" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

## Approvals

### List Approvals

```
GET /approvals
```

| Parameter  | Type    | Description                                |
| ---------- | ------- | ------------------------------------------ |
| `status`   | string  | `pending`, `approved`, `denied`, `expired` |
| `agent_id` | string  | Filter by agent                            |
| `page`     | integer | Page number                                |
| `limit`    | integer | Results per page                           |

```bash theme={null}
curl "https://api.meshai.dev/api/v1/approvals?status=pending" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

### Pending Approval Count

```
GET /approvals/pending/count
```

```bash theme={null}
curl https://api.meshai.dev/api/v1/approvals/pending/count \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  { "success": true, "data": { "count": 4 } }
  ```
</ResponseExample>

### Get Approval

```
GET /approvals/{request_id}
```

```bash theme={null}
curl https://api.meshai.dev/api/v1/approvals/17 \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

### Decide Approval

```
POST /approvals/{approval_id}/decide
```

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/approvals/apr_abc123/decide \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approved",
    "reason": "Agent configuration verified"
  }'
```

The `decision` field must be `approved` or `denied`.

## Oversight Metrics

### Agent Oversight Scorecard

```
GET /agents/{agent_id}/oversight
```

| Parameter | Type     | Description                                             |
| --------- | -------- | ------------------------------------------------------- |
| `start`   | datetime | Window start (default: 30 days ago, max range 180 days) |
| `end`     | datetime | Window end (default: now)                               |

```bash theme={null}
curl "https://api.meshai.dev/api/v1/agents/agt_abc123/oversight" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

Returns policy evaluation counts and fail rate, approval counts by outcome (including expired and pending), override rate, unattended rate, average approval latency, the number of defer-to-human policies applicable to the agent, its risk level, and whether its review is overdue. See [Oversight Metrics](/governance/oversight-metrics) for metric definitions and window semantics.

### Tenant Oversight Summary

```
GET /oversight/summary
```

Same metrics aggregated tenant-wide, plus `agents_evaluated`. Accepts the same `start` / `end` parameters.

## Incident Evidence Pack

```
GET /incidents/{incident_id}/evidence-pack
```

| Parameter      | Type    | Description                                                 |
| -------------- | ------- | ----------------------------------------------------------- |
| `window_hours` | integer | Telemetry window before `reported_at` (default 24, max 168) |

```bash theme={null}
curl "https://api.meshai.dev/api/v1/incidents/42/evidence-pack?window_hours=48" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

Assembles the incident report, agent and risk-classification snapshot, windowed policy evaluations, approvals with decisions, anomalies, usage totals, the audit trail including operator responses, the linked anomaly, and Article 73 deadline status into one document. Requires Professional plan or above. See [Incident Reporting](/governance/incidents#export-an-evidence-pack) for the full field reference.