API Reference

This reference is for building custom integrations in other languages.

Authentication

All API requests require your project API key in the X-API-Key header:

X-API-Key: as_your_api_key

Get your API key from the Dashboard.

Event Ingestion

POST /ingest-event

Records a permission check event.

Request:

{
  "agent_name": "SupportBot",
  "action": "permission_check",
  "scope": "read:orders",
  "allowed": true,
  "function_name": "get_order",
  "metadata": {}
}

Fields:

Response (201):

{
  "id": "uuid",
  "project_id": "uuid",
  "agent_id": "uuid",
  "agent_name": "SupportBot",
  "action": "permission_check",
  "scope": "read:orders",
  "allowed": true,
  "timestamp": "2024-01-15T10:30:00Z"
}

Example (cURL):

curl -X POST https://api.agentsudo.dev/ingest-event \
  -H "Content-Type: application/json" \
  -H "X-API-Key: as_your_api_key" \
  -d '{
    "agent_name": "SupportBot",
    "action": "permission_check",
    "scope": "read:orders",
    "allowed": true,
    "function_name": "get_order"
  }'

Error Codes

Error Response:

{
  "error": "Invalid API key"
}

Rate Limits

Building a Custom SDK

If you're building an SDK for another language, here's the minimal implementation:

# Pseudocode for any language
def send_event(api_key, agent_name, scope, allowed, function_name):
    POST "https://api.agentsudo.dev/ingest-event"
    Headers: {
        "Content-Type": "application/json",
        "X-API-Key": api_key
    }
    Body: {
        "agent_name": agent_name,
        "action": "permission_check", 
        "scope": scope,
        "allowed": allowed,
        "function_name": function_name
    }