AI Responses API

The Responses API is the engine behind investigations and "Ask CloudPeek." It's modelled on the OpenAI Responses API, so if you've used that, this will feel familiar. You use it to run the AI agent, with access to your connected tools, and stream its output.

Base path: /api/v1/responses · Permission resource: response. All requests require authentication.

Endpoints

Method	Path	Purpose	Permission
POST	`/responses/`	Create a model response (sync or streamed)	`response:create`
GET	`/responses/`	List stored responses	`response:read`
GET	`/responses/{response_id}`	Retrieve a stored response	`response:read`
DELETE	`/responses/{response_id}`	Delete a response	`response:delete`
GET	`/responses/{response_id}/input_items`	The stored input items	`response:read`
POST	`/responses/{response_id}/cancel`	Cancel a running execution	`response:write`
GET	`/responses/{response_id}/status`	`{ status, event_count }`	`response:read`
GET	`/responses/{response_id}/stream?last_seq=`	Reconnect to the SSE stream	`response:read`
GET	`/responses/active/{investigation_id}`	The active streaming response for an investigation	`response:read`
GET	`/responses/models`	List the tenant's available chat models	`response:read`
GET	`/responses/models/embedding`	List embedding models	`response:read`
GET	`/responses/agents`	List agents (for `agent_id`)	`response:read`
GET	`/responses/analytics`	Usage/analytics data	`response:read`

Create a response

POST /api/v1/responses/ runs the agent. Key body fields:

Field	Type	Notes
`model`	string	required: a model id from `GET /responses/models`
`input`	string \	array	the prompt, or a list of input items
`instructions`	string	optional system-style instructions
`stream`	bool	`true` to stream results over SSE (default `false`)
`tools`	array	tool configuration (optional)
`tool_choice`	string or object	how tools may be chosen
`temperature`	number	0-2
`max_output_tokens`	int	cap on output
`previous_response_id`	string	continue a prior response
`investigation`	object	`{ "title": "…" }` to create a new investigation for this run
`investigation_id`	int	attach to an existing investigation
`wiki_entity`	string	`"<type>:<key>"` to scope an "Ask the Wiki" question

Exactly one of investigation, investigation_id, wiki_entity (or a scan id) must be provided, and you can't combine investigation with investigation_id.

Synchronous example

curl -s -X POST "http://localhost:8000/api/v1/responses/" \
  -H "Authorization: Bearer $CLOUDPEEK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "bedrock/anthropic.claude-3-5-sonnet",
        "input": "Investigate incident 101 and summarise findings",
        "investigation": { "title": "IAM key triage" }
      }'

Streaming example (Server-Sent Events)

Set stream: true and read the text/event-stream response:

curl -N -X POST "http://localhost:8000/api/v1/responses/" \
  -H "Authorization: Bearer $CLOUDPEEK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "bedrock/anthropic.claude-3-5-sonnet",
        "input": "Investigate incident 101",
        "investigation_id": 42,
        "stream": true
      }'
# → a stream of response.* events

If a stream drops, reconnect with GET /responses/{response_id}/stream?last_seq=<n> to resume from where you left off, or poll GET /responses/{response_id}/status.

The response object

A response includes id, object: "response", created_at, status, output (the produced items), model, usage (token counts), metadata, and, when applicable, investigation_id and required_action (for example, a tool call awaiting HITL approval).

Discovering models

Use GET /responses/models to see which chat models your tenant has configured (via Model Providers), and GET /responses/models/embedding for embedding models. Pass the returned id as model when creating a response.

Investigations API: manage the investigation a response runs against.
Investigations and The Wiki: the UIs built on this API.