Investigations API
Create and manage investigations programmatically, read the agent's action stream, and generate reports.
Base path: /api/v1/investigate · Permission resource: investigation. Investigation IDs are numeric. All requests require authentication.
Endpoints
| Method | Path | Purpose | Permission |
|---|---|---|---|
| POST | /investigate/ | Create an investigation | investigation:create |
| GET | /investigate/ | List investigations | investigation:read |
| GET | /investigate/{id} | Get one (with its events) | investigation:read |
| PATCH | /investigate/{id} | Update title/query/status | investigation:update |
| DELETE | /investigate/{id} | Archive (soft-delete) | investigation:delete |
| GET | /investigate/{id}/actions | List events/actions | investigation:read |
| GET | /investigate/{id}/actions/{action_id} | Get one event | investigation:read |
| GET | /investigate/{id}/artifacts | List linked artifacts | investigation:read |
| GET | /investigate/{id}/responses | List linked AI responses | investigation:read |
| POST | /investigate/{id}/report | Generate a report | investigation:update |
| GET | /investigate/{id}/report | Get the current report | investigation:read |
Create an investigation
POST /api/v1/investigate/: body:
| Field | Type | Notes |
|---|---|---|
title | string | required, 1-500 chars |
query | string | the question to investigate |
curl -s -X POST "http://localhost:8000/api/v1/investigate/" \
-H "Authorization: Bearer $CLOUDPEEK_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "title": "Suspicious logins for jdoe", "query": "Investigate failed and successful logins for user jdoe in the last 24 hours" }'
# → 201 CreatedCreating an investigation here records it. To actually run the AI agent against it (and stream its work), use the AI Responses API with an investigation_id, that is the engine the web app uses.
The investigation object
A returned investigation includes: id (int), title, query, status, result, created_at, updated_at, last_message_at, created_by_id, events (a map of the recorded actions), and response_ids (linked AI responses).
status reflects the lifecycle: pending → planning → executing → completed / failed.
Reading the agent's work
GET /investigate/{id}/actionsreturns the events/actions the agent recorded. Filter withevent_type,author_type,author_id, and paginate withlimit(1-500, default 100) andoffset.GET /investigate/{id}/responseslists the AI responses linked to this investigation.GET /investigate/{id}/artifactslists artifacts the investigation produced (see Artifacts API).
Reports
POST /investigate/{id}/reportgenerates a written report (optional{ "model": "…" }to choose the model). Returns{ "report": … }.GET /investigate/{id}/reportreturns the current report, ornullif none exists.
Related
- Investigations: the UI and concepts.
- AI Responses API: run the agent and stream results.