Send an alert, your service map and the events around an incident. You get back the most likely root cause, the evidence for it, the failure path, what was ruled out and a next step, as JSON. Nothing is stored.
Request
POST https://api.boxai.dev/api/investigate
Content-Type: application/json
{ "incident": { ... } } your own incident
{ "sample": "login-5xx" } or one of the built-in samples
Field
Meaning
incident
The alert, services and events. Format below.
sample
checkout-latency, login-5xx or transfer-backlog. List them with GET /api/investigate/samples.
narrate
Optional. false skips the model-written incident update. The investigation itself never uses a model.
Which service alerted, what fired, and when (ISO 8601).
services[].name
Letters, digits, ., _, -. Unique.
services[].dependsOn
The services it calls. Every name must be in services.
services[].aliases
Optional. Up to 5 other names logs use for it, such as hostnames. At least 3 characters.
services[].kind
Optional label shown on the map, such as database.
events[].kind
log, metric, deploy, config or k8s.
events[].level
info, warn or error. Used for logs and Kubernetes events.
events[].value, baseline, unit
For metrics: the observed value and what is normal.
events[].version, previousVersion
For deploys. The previous version goes into the rollback step.
How it decides
Who can be the cause. Only services the alerting service depends on, directly or through others. Services that call it are impact. Anything else is unrelated.
What counts as an anomaly. A log or Kubernetes event at warn or error. A metric at twice or half its baseline or beyond. With a baseline of 0, any non-zero value.
Which events count. From 6 hours before the alert to 5 minutes after it. Others stay on the timeline, marked outside, and aren't scored.
Who blames whom. A log line names a service if it contains its name or an alias as a whole word.
Score. A change came first (+3), blamed by its callers (+2), nothing below it is failing (+2), hard errors (+1), first to break (+1). Out of 9.
Confidence. 7 to 9 is high, 4 to 6 medium, 0 to 3 low. If the runner-up is within a point, confidence is capped at medium and a caveat says so.
Response
Field
Meaning
investigation.rootCause
Service, score, confidence, the evidence for each check met, and what was missing. null if nothing upstream is anomalous.
investigation.hypotheses
Every suspect tested, best first.
investigation.chain
The failure path from root cause to the alerting service. confirmed means the caller's errors name the next hop.
investigation.ruledOut, impact
Suspects ruled out with the reason, and affected callers.
investigation.action
Next step: roll back, revert a config change, or page the owner.
investigation.caveats
Reasons to double-check the result. Empty when there are none.
investigation.timeline, graph, stats
Every event with its flags, the service map with each node's status, and counts.
narrative
The incident update. source is model or template; a template comes with a reason.
engine, engineMs, totalMs
Engine version and timings.
Errors and limits
Status
Error
When
400
invalid_json, missing_incident, invalid_alert, invalid_services, unknown_dependency, invalid_event and others
The body or incident is wrong. detail says what to fix.
404
unknown_sample
No sample with that id.
413
too_large
Body over 64 KB.
429
rate_limited
Too many requests from your address. Wait a minute.
Up to 60 services, 600 events and 400 characters per message. The model-written update shares a daily budget; when it is used up, you get the template and the investigation is unchanged.