4.2 KiB
MeshGuard API Reference
Base URL: {MESHGUARD_URL}/api/v1
All authenticated endpoints require: Authorization: Bearer <API_KEY>
Admin endpoints require: Authorization: Bearer <ADMIN_TOKEN>
Health
GET /health
Check gateway health. No auth required.
Response:
{
"status": "healthy",
"version": "1.4.2",
"uptime_seconds": 86400,
"services": {
"database": "connected",
"cache": "connected",
"queue": "connected"
}
}
Agents
GET /agents
List all agents in the organization.
Response:
{
"agents": [
{
"id": "ag_abc123",
"name": "my-agent",
"tier": "pro",
"status": "active",
"created_at": "2025-01-15T10:00:00Z",
"policies": ["pol_xyz789"]
}
],
"total": 1
}
POST /agents
Create a new agent.
Body:
{
"name": "my-agent",
"tier": "free|pro|enterprise"
}
Response: Agent object with id, api_key.
GET /agents/{id}
Get agent details by ID.
DELETE /agents/{id}
Delete an agent. Returns 204 No Content.
Policies
GET /policies
List all policies.
Response:
{
"policies": [
{
"id": "pol_xyz789",
"name": "rate-limit-policy",
"description": "Limit agent calls to 100/min",
"rules": [
{
"type": "rate_limit",
"max_requests": 100,
"window_seconds": 60
}
],
"created_at": "2025-01-15T10:00:00Z"
}
],
"total": 1
}
POST /policies
Create a new policy.
Body:
{
"name": "my-policy",
"description": "Policy description",
"rules": [
{
"type": "rate_limit",
"max_requests": 100,
"window_seconds": 60
},
{
"type": "content_filter",
"block_categories": ["pii", "credentials"]
},
{
"type": "scope_restriction",
"allowed_actions": ["read", "search"],
"denied_actions": ["delete", "admin"]
}
]
}
Rule Types
| Type | Fields | Description |
|---|---|---|
rate_limit |
max_requests, window_seconds |
Throttle request rate |
content_filter |
block_categories |
Block sensitive content categories |
scope_restriction |
allowed_actions, denied_actions |
Restrict agent capabilities |
time_window |
allowed_hours, timezone |
Restrict operation hours |
budget_limit |
max_cost_usd, period |
Cost guardrails |
GET /policies/{id}
Get policy details.
DELETE /policies/{id}
Delete a policy. Returns 204 No Content.
Audit Logs
GET /audit/logs
Query audit events.
Query Parameters:
| Param | Type | Description |
|---|---|---|
agent |
string | Filter by agent name |
action |
string | Filter by action type |
limit |
integer | Max results (default: 20, max: 1000) |
offset |
integer | Pagination offset |
from |
ISO 8601 | Start timestamp |
to |
ISO 8601 | End timestamp |
Actions: agent.create, agent.delete, agent.update, policy.create, policy.update, policy.delete, policy.attach, policy.detach, auth.login, auth.revoke, violation.rate_limit, violation.content_filter, violation.scope
Response:
{
"events": [
{
"id": "evt_001",
"timestamp": "2025-01-15T10:30:00Z",
"action": "agent.create",
"agent": "my-agent",
"actor": "[email protected]",
"details": {
"tier": "pro"
},
"ip": "192.168.1.1"
}
],
"total": 42,
"limit": 20,
"offset": 0
}
Organization Signup
POST /orgs/signup (Admin token required)
Create a new organization.
Body:
{
"name": "Acme Corp",
"email": "[email protected]"
}
Response:
{
"org_id": "org_abc123",
"name": "Acme Corp",
"api_key": "mg_live_...",
"admin_token": "mg_admin_...",
"dashboard_url": "https://dashboard.meshguard.app/org/org_abc123"
}
Error Responses
All errors follow this format:
{
"error": {
"code": "unauthorized",
"message": "Invalid or expired API key",
"status": 401
}
}
Common error codes: unauthorized (401), forbidden (403), not_found (404), rate_limited (429), internal_error (500).