Events¶

Ingest a ContextEvent into the Noctuary state store. This is the core API called by the Noctuary Agent after a vendor plugin extracts a signal from a log line.

POST /v1/events¶

Requires an ingest API key. The agent must be registered (via POST /v1/agents/register) before sending events.

curl -X POST https://api.noctuary.io/v1/events \
  -H "Authorization: Bearer noc_ingest_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "service_name": "payments-api",
    "vendor": "argocd",
    "entity": "payments-api",
    "event_type": "deploy",
    "new_value": "syncing:a4f2c1",
    "confidence": 0.97,
    "ttl_seconds": 3600,
    "timestamp": "2026-05-31T02:10:41Z",
    "raw_line": "time=\"2026-05-31T02:10:41Z\" level=info msg=\"Sync operation starting\" app=payments-api revision=a4f2c1"
  }'

Response: 201 Created (no body)

Request body¶

Field	Type	Required	Description
`service_name`	string	Yes	OTel `service.name` — must match your service
`vendor`	string	Yes	Plugin that detected the event: `argocd`, `kubernetes`, `postgres`
`entity`	string	Yes	The specific resource affected: app name, pod name, table name
`event_type`	string	Yes	See event types below
`old_value`	string	No	Previous state (e.g. previous deploy SHA, previous config value)
`new_value`	string	No	New state (e.g. new deploy SHA, new config value)
`actor`	string	No	Who or what triggered the change: CI pipeline, username, etc.
`sha`	string	No	Git SHA for deploy events
`confidence`	float	Yes	Plugin confidence: `0.0 < confidence <= 1.0`
`ttl_seconds`	integer	Yes	How long this event is relevant (seconds). Must be > 0.
`timestamp`	string	No	ISO 8601 event timestamp. Defaults to server receipt time.
`raw_line`	string	No	Original log line (stored for audit, never transmitted further)

Event types¶

Type	Vendors	Description
`deploy`	argocd	Application sync / deployment
`restart`	kubernetes	Pod restart (OOMKill, CrashLoop, probe failure)
`saturation`	kubernetes, postgres	Resource exhaustion (memory, connections, I/O)
`flag_change`	any	Feature flag state change
`circuit_open`	any	Circuit breaker opened
`dependency_failure`	any	Downstream dependency failure

Side effects¶

On every successful ingest:

The service is created or updated in the database
The event is stored in the context_events table with an expiry timestamp (now() + ttl_seconds)
The event is merged into the service's Redis state window
The agent's last_seen_at is updated (counts as a heartbeat)

Errors¶

Status	Body	Cause
`400`	`service_name, vendor, and entity are required`	Missing required fields
`400`	`confidence must be between 0 and 1`	Invalid confidence value
`400`	`ttl_seconds must be positive`	Invalid TTL
`403`	`agent not registered`	Call `POST /v1/agents/register` first