Compliance API - MeshAI Documentation

{
  "success": true,
  "data": {
    "period_start": "2026-08-01T00:00:00+00:00",
    "period_end": "2026-09-01T00:00:00+00:00",
    "generated_at": "2026-09-01T00:00:01+00:00",
    "distinct_models_returned": 1,
    "total_rows": 1,
    "returned_rows": 1,
    "truncated": false,
    "model_attribution": {
      "confirmed": "gen_ai.response.model",
      "fallback": "gen_ai.request.model or direct telemetry model_name",
      "warning": "request_fallback rows do not prove the exact model version served by the provider"
    },
    "rows": [
      {
        "provider": "openai",
        "model": "gpt-4.1-2026-06-15",
        "attribution_source": "response",
        "agent_id": "agt_abc123",
        "agent_name": "production-summarizer",
        "team_id": "team_platform",
        "team_name": "Platform",
        "first_observed_at": "2026-08-10T14:30:00+00:00",
        "last_observed_at": "2026-08-10T14:30:00+00:00",
        "requests": 24,
        "input_tokens": 12000,
        "output_tokens": 4000,
        "total_tokens": 16000,
        "estimated_cost_usd": "0.120000"
      }
    ]
  }
}

{
  "success": true,
  "data": {
    "period_start": "2026-08-01T00:00:00+00:00",
    "period_end": "2026-09-01T00:00:00+00:00",
    "generated_at": "2026-09-01T00:00:01+00:00",
    "distinct_models_returned": 1,
    "total_rows": 1,
    "returned_rows": 1,
    "truncated": false,
    "model_attribution": {
      "confirmed": "gen_ai.response.model",
      "fallback": "gen_ai.request.model or direct telemetry model_name",
      "warning": "request_fallback rows do not prove the exact model version served by the provider"
    },
    "rows": [
      {
        "provider": "openai",
        "model": "gpt-4.1-2026-06-15",
        "attribution_source": "response",
        "agent_id": "agt_abc123",
        "agent_name": "production-summarizer",
        "team_id": "team_platform",
        "team_name": "Platform",
        "first_observed_at": "2026-08-10T14:30:00+00:00",
        "last_observed_at": "2026-08-10T14:30:00+00:00",
        "requests": 24,
        "input_tokens": 12000,
        "output_tokens": 4000,
        "total_tokens": 16000,
        "estimated_cost_usd": "0.120000"
      }
    ]
  }
}

Article 50 Evidence Pack

GET /compliance/article-50/evidence-pack

Generate a recorded-evidence report for the AI-disclosure and content-marking tracks. This endpoint requires the governance:read scope and a Professional or higher plan. The optional start and end parameters are ISO 8601 timestamps. The default window is the previous 30 days, and a requested window cannot exceed 395 days. start must be earlier than end; otherwise the API returns 400. MeshAI clamps the effective window to the tenant’s retained telemetry. Compare requested_start and requested_end with effective_start and effective_end; retention_clamped is true when they differ.

curl "https://api.meshai.dev/api/v1/compliance/article-50/evidence-pack?start=2026-08-01T00:00:00Z&end=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

The report uses these honest recorded-evidence statuses:

Status	Meaning
`check_not_configured`	No enabled check or evaluation was recorded
`no_recorded_evidence`	No passing evidence was recorded, including an empty or skip-only window
`gaps_recorded`	At least one evaluated interaction recorded a failure
`evidence_recorded`	Passing evidence was recorded with no recorded failures

Every track reports applicability: "not_determined", and the assessment reports coverage: "unquantified". MeshAI does not infer that Article 50 applies, prove that a disclosure was visible, validate a content mark, or prove that every generated output was evaluated. Missing evidence is not proof of non-compliance. interactions_with_pass and interactions_with_fail are distinct counts within each result. They can overlap when multiple policies disagree about the same interaction. Review gaps before relying on the summaries. The report calls out unquantified coverage, unlinked legacy evaluations, record or inventory truncation, and model-version request fallbacks when present. Per-track records contain at most 200 representative interactions, ordered from the earliest evaluation in the effective window. Aggregate counts remain authoritative when records_truncated is true. The evidence_integrity section is also scoped. Hash-chain heads and external checkpoint receipts cover policy evaluations and audit events. They do not cover token usage records or the model inventory. See Article 50 Transparency Evidence for instrumentation and dashboard instructions.

GPAI Model Inventory

GET /compliance/model-inventory

Return model usage grouped by provider, model, agent, and team. The default period follows your telemetry retention window. You can supply start and end ISO 8601 timestamps for a period of up to 395 days and limit from 1 to 5,000.

curl "https://api.meshai.dev/api/v1/compliance/model-inventory?start=2026-08-01T00:00:00Z&end=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

Each row’s attribution_source is response when telemetry supplied gen_ai.response.model. It is request_fallback when only the requested or directly reported model is known. A fallback row does not confirm the exact model version served by the provider.

{
  "success": true,
  "data": {
    "period_start": "2026-08-01T00:00:00+00:00",
    "period_end": "2026-09-01T00:00:00+00:00",
    "generated_at": "2026-09-01T00:00:01+00:00",
    "distinct_models_returned": 1,
    "total_rows": 1,
    "returned_rows": 1,
    "truncated": false,
    "model_attribution": {
      "confirmed": "gen_ai.response.model",
      "fallback": "gen_ai.request.model or direct telemetry model_name",
      "warning": "request_fallback rows do not prove the exact model version served by the provider"
    },
    "rows": [
      {
        "provider": "openai",
        "model": "gpt-4.1-2026-06-15",
        "attribution_source": "response",
        "agent_id": "agt_abc123",
        "agent_name": "production-summarizer",
        "team_id": "team_platform",
        "team_name": "Platform",
        "first_observed_at": "2026-08-10T14:30:00+00:00",
        "last_observed_at": "2026-08-10T14:30:00+00:00",
        "requests": 24,
        "input_tokens": 12000,
        "output_tokens": 4000,
        "total_tokens": 16000,
        "estimated_cost_usd": "0.120000"
      }
    ]
  }
}

Export Model Inventory

GET /compliance/model-inventory/export?fmt=csv

Download the same inventory as csv or json. Export requires a Professional or Enterprise plan. The query accepts the same start, end, and limit parameters as the JSON endpoint.

curl -OJ "https://api.meshai.dev/api/v1/compliance/model-inventory/export?fmt=csv" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

Readiness Score

GET /compliance/readiness

Get the EU AI Act readiness score for your tenant.

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

{
  "success": true,
  "data": {
    "total_score": 85,
    "max_score": 120,
    "rating": "good",
    "components": [
      { "name": "agent_registry", "score": 20, "max_score": 20, "status": "complete" },
      { "name": "risk_classification", "score": 15, "max_score": 20, "status": "partial" },
      { "name": "governance_policies", "score": 15, "max_score": 15, "status": "complete" },
      { "name": "human_oversight", "score": 15, "max_score": 20, "status": "partial" },
      { "name": "audit_trail", "score": 15, "max_score": 15, "status": "complete" },
      { "name": "fria_completion", "score": 5, "max_score": 20, "status": "partial" },
      { "name": "incident_readiness", "score": 0, "max_score": 10, "status": "missing" }
    ],
    "recommendations": [
      "Classify the remaining 2 agents with a risk level",
      "Complete FRIA for agents: hr-screener, loan-evaluator"
    ],
    "assessed_at": "2026-03-17T10:00:00Z"
  }
}

FRIA (Fundamental Rights Impact Assessment)

Get FRIA

GET /agents/{agent_id}/fria

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

{
  "success": true,
  "data": {
    "id": "fria_abc123",
    "agent_id": "agt_abc123",
    "version": 1,
    "status": "submitted",
    "processes": "The AI agent reviews job applications...",
    "frequency_and_scope": "Used daily by 5 HR managers...",
    "categories_of_persons": "Job applicants...",
    "specific_risks": "Risk of discriminatory bias...",
    "human_oversight_measures": "All AI-ranked lists reviewed by human...",
    "risk_mitigation_measures": "If bias detected: suspend agent...",
    "created_at": "2026-03-17T10:00:00Z",
    "created_by": "user@company.com"
  }
}

Create FRIA

POST /agents/{agent_id}/fria

All six fields are required. See FRIA for field descriptions.

curl -X POST https://api.meshai.dev/api/v1/agents/agt_abc123/fria \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "processes": "The AI agent reviews job applications and ranks candidates...",
    "frequency_and_scope": "Used daily by 5 HR managers. ~500 applications/month.",
    "categories_of_persons": "Job applicants, EU residents of all ages.",
    "specific_risks": "Risk of discriminatory bias in candidate ranking.",
    "human_oversight_measures": "All AI-ranked lists reviewed by human HR manager.",
    "risk_mitigation_measures": "If bias detected: suspend agent, notify applicants."
  }'

Submit FRIA

POST /fria/{fria_id}/submit

Finalizes the FRIA and logs it in the audit trail.

curl -X POST https://api.meshai.dev/api/v1/fria/42/submit \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

Transparency Card

GET /agents/{agent_id}/transparency-card

Get the auto-generated transparency card for an agent.

curl https://api.meshai.dev/api/v1/agents/agt_abc123/transparency-card \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

{
  "success": true,
  "data": {
    "agent_id": "agt_abc123",
    "agent_name": "production-summarizer",
    "purpose": "Summarizes customer support tickets",
    "framework": "crewai",
    "model_provider": "openai",
    "model_name": "gpt-4o",
    "risk_level": "limited",
    "capabilities": ["Text summarization", "Ticket categorization"],
    "limitations": ["May miss context in multi-language tickets"],
    "human_oversight": "Output reviewed by support team leads",
    "data_sources": "Customer support ticket text (no PII stored)",
    "generated_at": "2026-03-17T10:00:00Z"
  }
}

Incidents

Create Incident

POST /incidents

curl -X POST https://api.meshai.dev/api/v1/incidents \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_abc123",
    "title": "Discriminatory output in hiring agent",
    "severity": "high",
    "description": "The HR screening agent systematically ranked female candidates lower...",
    "impact": "Approximately 120 applicants affected.",
    "immediate_actions": "Agent suspended immediately.",
    "root_cause": "Training data contained historical hiring bias.",
    "affected_persons_count": 120,
    "involves_health_or_death": false
  }'

Get Incident

GET /incidents/{incident_id}

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

Update Incident

PATCH /incidents/{incident_id}

curl -X PATCH https://api.meshai.dev/api/v1/incidents/inc_abc123 \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "mitigated",
    "update_note": "All affected applications manually re-reviewed."
  }'

Authority Notification

There is no separate notify-authority endpoint. Record that a competent authority has been notified by updating the incident: PATCH /incidents/{incident_id} with body field authority_notified: true. See Incident Reporting for the full workflow and deadlines.

​Article 50 Evidence Pack

​GPAI Model Inventory

​Export Model Inventory

​Readiness Score

​FRIA (Fundamental Rights Impact Assessment)

​Get FRIA

​Create FRIA

​Submit FRIA

​Transparency Card

​Incidents

​Create Incident

​Get Incident

​Update Incident

​Authority Notification