API ReferencePOST /events

POST /events

Send an agent event for monitoring and rule evaluation.

Request Body

FieldTypeRequiredDescription
actionstringYes*Agent action name
event_typestringYes*Alternative to action
messagestringNoHuman readable description
severitystringNolow | medium | high | critical
metadataobjectNoAny key/value pairs
resourcestringNoTarget resource
user_idstringNoAssociated user
tagsstring[]NoFilterable tags
requires_approvalbooleanNoForce human approval
callback_urlstringNoWebhook for approval result

* Provide either action or event_type.

Response

FieldTypeDescription
successbooleanEvent accepted
event_idstringEvent ID
rules_matchednumberRules that fired
blockedbooleanIf true, stop the action
approval_idstring?Present if approval required
incident_createdbooleanIncident opened
ai_classificationobject?Risk score + label

Error Codes

CodeMeaningFix
401Invalid API keyCheck key in dashboard
403Action blocked by ruleReview rules
422Invalid payloadCheck required fields
429Plan limit reachedUpgrade plan
500Server errorRetry or contact support
AuthenticationGET /events

Was this helpful?

Something wrong? Open an issue on GitHub
bash
"tk-cmt"># POST /events
curl -X POST https:"tk-cmt">//www.aigodfather.ai/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "payment_processed",
    "message": "Payment processed",
    "severity": "info",
    "metadata": {
      "amount": 4200,
      "currency": "EUR",
      "vendor": "stripe",
      "userId": "usr_456"
    }
  }'

"tk-cmt"># Response (201)
{
  "success": true,
  "event_id": "evt_01HXYZ123",
  "rules_matched": 1,
  "blocked": false,
  "approval_id": null,
  "incident_created": false,
  "ai_classification": {
    "ai_risk_score": 35,
    "ai_classification": "elevated"
  }
}

"tk-cmt"># Response (403 — Blocked)
{
  "success": false,
  "status": "blocked",
  "message": "Action blocked by rule: High Value Guard"
}

"tk-cmt"># Response (202 — Approval Required)
{
  "status": "pending_approval",
  "approval_id": "apr_01HXYZ456",
  "poll_url": "/v1/approvals/apr_01HXYZ456"
}