Security API - MeshAI Documentation

All endpoints on this page except the read-only ownership and relationship lookups require the admin scope.

Kill Switch

Block an Agent

POST /agents/{agent_id}/block

Immediately blocks the agent from making requests through the proxy.

curl -X POST https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/block \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Suspected credential leak" }'

Unblock an Agent

POST /agents/{agent_id}/unblock

curl -X POST https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/unblock \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

Quarantine

Quarantine an Agent

POST /agents/{agent_id}/quarantine

Flags a shadow or misbehaving agent as quarantined and blocks it in the proxy layer.

curl -X POST https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/quarantine \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Unregistered agent discovered calling production models" }'

Release from Quarantine

POST /agents/{agent_id}/release-quarantine

curl -X POST https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/release-quarantine \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

List Quarantined Agents

GET /agents/quarantined

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

Lifecycle

List Expired Agents

GET /agents/expired

Agents whose expires_at has passed.

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

List Agents Due for Review

GET /agents/due-review

Agents whose review_date has passed.

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

Configure Lifecycle

PATCH /agents/{agent_id}/lifecycle

Sets an agent’s expiry date, access review cadence, and/or sponsor. All fields are optional; review_frequency must be weekly, monthly, quarterly, or annually and drives the computed review_date.

curl -X PATCH https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/lifecycle \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_at": "2026-12-31T00:00:00Z",
    "review_frequency": "quarterly",
    "sponsor_id": "hcunha"
  }'

Ownership (ABAC)

Assign an Owner

POST /agents/{agent_id}/owners

owner_type must be user, team, or service_account. owner_id is a caller-supplied external identifier (e.g. an SSO user ID), not a MeshAI-generated ID. permissions defaults to {"can_invoke": true, "can_configure": false, "can_delete": false} when omitted.

curl -X POST https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/owners \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "owner_type": "user",
    "owner_id": "sso-user-4821",
    "owner_name": "Jane Doe"
  }'

List Agent Owners

GET /agents/{agent_id}/owners

Requires the registry:read scope.

curl https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/owners \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

Remove an Owner

DELETE /agents/{agent_id}/owners/{owner_id}

owner_id here is the integer ID of the ownership record returned by POST /agents/{agent_id}/owners (not the external owner_id string).

curl -X DELETE https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/owners/7 \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

Returns 204 No Content on success.

List Agents by Owner

GET /owners/{owner_id}/agents

Requires the registry:read scope. owner_id is the external identifier used when the owner was assigned.

curl https://api.meshai.dev/api/v1/owners/sso-user-4821/agents \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

Relationships

Agent Relationships

GET /agents/{agent_id}/relationships

Requires the registry:read scope. Lists the models, providers, tools, and other agents this agent calls.

curl https://api.meshai.dev/api/v1/agents/01HQZXK3VJ3XZ9K8QYNPBC7G4T/relationships \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

Relationship Graph

GET /relationships/graph

Requires the registry:read scope. Returns the full tenant-wide agent dependency graph as nodes and edges.

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

{
  "success": true,
  "data": {
    "nodes": [
      { "id": "01HQZXK3VJ3XZ9K8QYNPBC7G4T", "name": "production-summarizer", "type": "agent", "status": "healthy", "blocked": false, "framework": "crewai" },
      { "id": "model:gpt-4o", "name": "gpt-4o", "type": "model" }
    ],
    "edges": [
      { "source": "01HQZXK3VJ3XZ9K8QYNPBC7G4T", "target": "model:gpt-4o", "type": "calls_model", "request_count": 1204 }
    ]
  }
}

Security Posture

GET /security/posture

Composite tenant security score (0-100) across six weighted dimensions: agent ownership, agent expiry, access reviews, quarantine status, kill switch status, and risk classification coverage.

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

{
  "success": true,
  "data": {
    "score": 78,
    "max_score": 100,
    "components": [
      { "name": "Agent Ownership", "max_score": 20, "score": 16, "detail": "8/10 agents have assigned owners" },
      { "name": "Agent Expiry", "max_score": 15, "score": 15, "detail": "No expired agents" },
      { "name": "Access Reviews", "max_score": 15, "score": 12, "detail": "1 overdue" },
      { "name": "Quarantine Status", "max_score": 15, "score": 15, "detail": "None quarantined" },
      { "name": "Kill Switch Status", "max_score": 15, "score": 10, "detail": "1 agents blocked" },
      { "name": "Risk Classification", "max_score": 20, "score": 10, "detail": "5/10 agents classified" }
    ],
    "assessed_at": "2026-03-17T10:30:00Z"
  }
}

​Kill Switch

​Block an Agent

​Unblock an Agent

​Quarantine

​Quarantine an Agent

​Release from Quarantine

​List Quarantined Agents

​Lifecycle

​List Expired Agents

​List Agents Due for Review

​Configure Lifecycle

​Ownership (ABAC)

​Assign an Owner

​List Agent Owners

​Remove an Owner

​List Agents by Owner

​Relationships

​Agent Relationships

​Relationship Graph

​Security Posture