Chat & pentest execution

The streaming /chat endpoint on the agent backend — general agentic chat (the agent harness) and launching guided or automatic pentests over Server-Sent Events.

Everything that runs an agent — answering a chat, working a long-running task, or executing a pentest — goes through a single endpoint on the agent backend, separate from the REST API:

POST https://aleex.aleex-rank.ai/chat

Unlike the rest of this reference (which is relative to https://api.aleex-rank.ai/api/v2), the execution endpoints live on https://aleex.aleex-rank.ai. They authenticate with the same credentials — X-API-Key: rk_... or Authorization: Bearer <jwt> — and respond with a Server-Sent Events stream (Content-Type: text/event-stream) rather than a JSON envelope.

POST /chat is one endpoint with three jobs, selected by the body you send:

You send	What runs
`agent_id`	A general chat turn. One-shot, or the full agent harness if the agent qualifies (see below).
`pentest_id` + `mode="guided"` + `phase_id`	One pentest phase, on demand.
`pentest_id` + `mode="automatic"`	The whole pentest — every phase, in the background, streamed as it happens.

Request body

POST /chat accepts application/json (or multipart/form-data when attaching files). Numeric fields tolerate both numbers and strings.

Field	Type	Notes
`user_prompt`	string	The message. Required.
`agent_id`	int	The agent to run. Required for general chat.
`agent_type`	string	`"general"` or `"pentest"`. Inferred when `pentest_id` is set.
`chat_id`	int	Persist the turn and reuse conversation context across calls.
`pentest_id`	int	Required to run a pentest.
`mode`	string	`"guided"` or `"automatic"`. Pentest only.
`phase_id`	int	The phase to execute. Required for `guided` mode.
`context`	array	Explicit history as `[{ "userPrompt": "...", "aiResponse": "..." }]`. Omit when `chat_id` is provided.

Attachments are sent as multipart/form-data: a files array of { "file_data": "<base64>", "file_name": "report.pdf" } (up to 10 files, 50 MB combined; PDF, JSON, PNG, JPEG, WEBP, GIF). The prompt is screened by a guardrail before anything runs — a blocked prompt returns 422 Unprocessable Entity.

General chat

curl -N https://aleex.aleex-rank.ai/chat \
  -H "X-API-Key: rk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 23, "chat_id": 14, "user_prompt": "Enumerate the exposed services and summarize the risk."}'

When the agent’s type is general, its model supports agentic execution, and it has at least one tool, /chat runs the agent harness: it plans, calls tools, reflects and keeps working — across many iterations, with context compaction for long tasks — until the request is fully covered. Otherwise it answers in a single pass. Either way the answer streams as content events. See Agent harness & long-running tasks for what the loop does and Streaming for the event payloads.

Launching a pentest

Automatic mode runs the full engagement in the background and streams progress; the run keeps going even if the client disconnects.

{
  "pentest_id": 42,
  "mode": "automatic",
  "user_prompt": "Start the assessment."
}

Guided mode executes one phase per call — send phase_id for the phase you want, and call again for the next:

{
  "pentest_id": 42,
  "mode": "guided",
  "phase_id": 1,
  "user_prompt": "Run reconnaissance."
}

Before launching, configure the pentest and its agents through the Pentests API. After it finishes, process findings and generate the report — those endpoints also live on this backend and are listed under Run, process and report.

The SSE stream

Each event arrives as a line data: <json>\n\n; comment lines beginning with : are keepalives and can be ignored. Every payload carries a type discriminator:

`type`	Emitted when
`content`	A chunk of the assistant’s answer, streamed token by token.
`agent_event`	Live agent activity (thinking, tool calls, sub-agents, orchestration). Never part of the answer text.
`queued`	The pentest is waiting for a free execution slot.
`ready`	A slot opened and the run is starting.
`phase_start`	An automatic-mode phase began.
`phase_complete`	A phase finished.
`phase_retry`	A phase is being retried.
`processing_vulnerabilities`	Findings are being analyzed at the end of an automatic run.
`vulnerabilities_complete`	Findings have been stored.
`complete`	The stream finished successfully (terminal).
`error`	Something failed; carries an `error` message (terminal).
`cancelled`	The run was cancelled (terminal).
`reconnected`	First event when re-attaching to a running pentest.

Build the answer only from content events. agent_event items describe what the agent is doing and belong in an activity timeline — never concatenate them into the message body. The full agent_event taxonomy is documented in Streaming.

Reconnecting and cancelling

Long pentests outlive a dropped connection. Re-attach to an in-progress automatic run, or cancel one, with the companion endpoints on this backend:

GET  https://aleex.aleex-rank.ai/pentest/{id}/stream
POST https://aleex.aleex-rank.ai/pentest/{id}/cancel

GET /pentest/{id}/stream opens a fresh SSE stream that begins with a reconnected event carrying the current phase and progress, then continues with the same event types as above. POST /pentest/{id}/cancel signals the background run to stop; it emits a cancelled event and marks the pentest failed.

From the SDK these are client.ai.chat.stream(...), client.pentests.stream(pentest_id) and client.pentests.cancel(pentest_id) — see Streaming. For chat session management (creating, renaming, sharing the conversations this endpoint writes to), see the Chats API.