API Reference

The SURADAR REST API is available at https://api.suradar.dev. All requests use JSON and require authentication.

Authentication

Include your API key as a Bearer token in the Authorization header:

Authorization: Bearer sk_live_abc123...

Endpoints

POST /v1/agents

Enroll a new agent in your organization.

Request:

{
  "name": "order-processor",
  "description": "Processes incoming purchase orders",
  "org_id": "org_xyz789",
  "metadata": {
    "team": "commerce",
    "environment": "production"
  }
}

Response (201):

{
  "id": "agt_abc123",
  "name": "order-processor",
  "status": "active",
  "created_at": "2026-04-15T08:00:00Z",
  "credential": "cred_..."
}

GET /v1/agents/:id

Retrieve details for an enrolled agent.

Response (200):

{
  "id": "agt_abc123",
  "name": "order-processor",
  "description": "Processes incoming purchase orders",
  "status": "active",
  "created_at": "2026-04-15T08:00:00Z",
  "last_active_at": "2026-04-15T12:34:56Z",
  "metadata": {
    "team": "commerce",
    "environment": "production"
  }
}

POST /v1/policies

Create a governance policy.

Request:

{
  "name": "production-rate-limit",
  "scope": "org",
  "rules": [
    {
      "type": "rate_limit",
      "max_requests_per_minute": 1000
    },
    {
      "type": "action_allowlist",
      "actions": ["read", "write"]
    }
  ]
}

Response (201):

{
  "id": "pol_def456",
  "name": "production-rate-limit",
  "scope": "org",
  "status": "active",
  "created_at": "2026-04-15T08:00:00Z"
}

GET /v1/audit

Query the audit log. Supports filtering by agent, action, and time range.

Query parameters:

Parameter	Type	Description
agent_id	string	Filter by agent ID
action	string	Filter by action type
from	ISO 8601	Start of time range
to	ISO 8601	End of time range
limit	integer	Max results (default: 100, max: 1000)

Response (200):

{
  "events": [
    {
      "id": "evt_ghi789",
      "agent_id": "agt_abc123",
      "action": "write",
      "resource": "orders/12345",
      "result": "allowed",
      "timestamp": "2026-04-15T12:34:56Z"
    }
  ],
  "has_more": true,
  "cursor": "cur_..."
}

GET /v1/usage

Retrieve usage metrics for your organization.

Response (200):

{
  "period": "2026-04",
  "total_requests": 142857,
  "agents_active": 23,
  "policy_evaluations": 142857,
  "actions_denied": 312
}

Error Format

All errors follow a consistent format:

{
  "error": {
    "code": "invalid_request",
    "message": "The 'name' field is required.",
    "status": 400
  }
}

Error Codes

Code	Status	Description
invalid_request	400	Missing or malformed parameters
unauthorized	401	Invalid or missing API key
forbidden	403	Valid key but insufficient permissions
not_found	404	Resource does not exist
conflict	409	Resource already exists
rate_limited	429	Too many requests
internal_error	500	Server error — retry with backoff

Rate Limits

Plan	Requests per minute
Starter	100
Pro	1,000
Enterprise	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1713168000

Next Steps

• Connect external systems via Integrations
• Review the Configuration reference for SDK and environment setup