Governance API - MeshAI Documentation

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

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

{
  "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 }
}

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

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

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

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

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

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.

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"
      }
    ]
  }'

{
  "success": true,
  "data": { "created": 1, "updated": 0, "failed": 0 }
}

Policies

List Policies

GET /policies

curl https://api.meshai.dev/api/v1/policies \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

Create Policy

POST /policies

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 for config details.

Get Policy

GET /policies/{policy_id}

Update Policy

PATCH /policies/{policy_id}

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}

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.

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.

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.

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"
  }'

{
  "success": true,
  "data": [
    {
      "policy_id": 3,
      "policy_name": "production-model-allowlist",
      "policy_type": "model_allowlist",
      "result": "pass",
      "reason": null
    }
  ]
}

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

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

curl "https://api.meshai.dev/api/v1/approvals?status=pending" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

Pending Approval Count

GET /approvals/pending/count

curl https://api.meshai.dev/api/v1/approvals/pending/count \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

{ "success": true, "data": { "count": 4 } }

Get Approval

GET /approvals/{request_id}

curl https://api.meshai.dev/api/v1/approvals/17 \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

Decide Approval

POST /approvals/{approval_id}/decide

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)

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 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)

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 for the full field reference.

​Audit Trail

​List Audit Events

​Export Audit Events

​Risk Classification

​Get Classification

​Classify Agent

​Get AI Suggestion

​List Risk Classifications

​Bulk Classify Agents

​Policies

​List Policies

​Create Policy

​Get Policy

​Update Policy

​Delete Policy

​List Policy Templates

​Create Policy from Template

​Dry Run Evaluate

​List Policy Evaluations

​Approvals

​List Approvals

​Pending Approval Count

​Get Approval

​Decide Approval

​Oversight Metrics

​Agent Oversight Scorecard

​Tenant Oversight Summary

​Incident Evidence Pack