Base URL and authentication

Send requests to https://{your_subdomain}.nousai.com, authenticated with the x-api-key header provided to you by Nous AI. See API Reference for keys and the errors shared by every API.

Overview

The streaming endpoints run exactly the same turn as the JSON endpoints, but respond with Content-Type: text/event-stream (Server-Sent Events) and emit progress while the agent works. Use POST /api/v1/search-agent/conversations/stream/ to start a conversation, and POST /api/v1/search-agent/conversations/{conversation_id}/turns/stream/ for follow-ups. The request body and headers are identical to the non-streaming endpoints.

Streaming carries progress, not answer tokens: the answer arrives whole in the final result frame, whose payload is exactly the JSON endpoint's response body.

Frame contract

Each frame is a standard SSE event: an event: line naming the frame type and a data: line carrying a JSON payload. Comment frames (lines starting with :) are keep-alives; ignore them.

Stage names

Stages report progress only. The cited source documents arrive once, with the answer, in the result frame.

event: start
data: {}

event: stage
data: {"stage": "understanding"}

event: stage
data: {"stage": "searching", "round": 1}

event: stage
data: {"stage": "writing"}

event: result
data: {"conversation_id": "7f9d...", "ai_summary": "EMEA Q3 revenue was...", ...}

Note that the browser EventSource API only supports GET; consume these endpoints with fetch and a stream reader, or any SSE client library that supports POST. Bad input and unknown conversations are rejected with a JSON 400/404 before the stream opens; once the stream has opened, failures arrive as an error frame. Disconnecting mid-stream does not cancel the turn: it completes and is stored on the conversation.

Base URL and authentication

Send requests to https://{your_subdomain}.nousai.com, authenticated with the x-api-key header provided to you by Nous AI. See API Reference for keys and the errors shared by every API.

List conversations

GET /api/v1/search-agent/conversations/ returns the conversations created with your API key, newest first.

{
	"conversations": [
		{
			"id": "7f9d2c48-1a9e-4a41-9c9a-1f2f2b1f6d2e",
			"title": null,
			"display_title": "What was EMEA revenue in Q3?",
			"status": "active",
			"created_at": "2026-08-12T09:00:00Z",
			"updated_at": "2026-08-12T09:05:00Z",
			"turn_count": 2
		}
	]
}

Read a conversation thread

GET /api/v1/search-agent/conversations/{conversation_id}/ returns the full thread: every turn with its query, answer, cited documents, and status, in order. The top-level disabled flag is true when the conversation can take no further turns (it reached the model's context limit).

{
	"id": "7f9d2c48-1a9e-4a41-9c9a-1f2f2b1f6d2e",
	"title": null,
	"status": "active",
	"created_at": "2026-08-12T09:00:00Z",
	"updated_at": "2026-08-12T09:05:00Z",
	"disabled": false,
	"turns": [
		{
			"id": "a5b0f9f0-6a5f-4f5b-9e0d-8f6a1c2d3e4f",
			"ordinal": 0,
			"query": "What was EMEA revenue in Q3?",
			"status": "completed",
			"created_at": "2026-08-12T09:00:00Z",
			"ai_summary": "EMEA Q3 revenue was...",
			"documents": [ ... ],
			"feedback_rating": null
		}
	]
}

Error Responses

Unknown Conversation

• Code: 404 Not Found
• Content: {"error": "Conversation not found."}

Invalid API Key

• Code: 403 Forbidden
• Content: {"detail": "Invalid API key"}

Base URL and authentication

Send requests to https://{your_subdomain}.nousai.com, authenticated with the x-api-key header provided to you by Nous AI. See API Reference for keys and the errors shared by every API.

Overview

Record a rating on a turn's answer, for example when a user of your portal clicks thumbs up or down. Feedback helps Nous AI monitor and improve answer quality for your tenant.

Request

Body

{
	"rating": "negative",
	"issue_type": "wrong_answer",
	"detail": "The Q3 figure is from the draft report."
}

Response

Success Response

• Code: 200 OK
• Content: {"status": "ok", "feedback_rating": "negative"}

Error Responses

Invalid Rating

• Code: 400 Bad Request
• Content: {"error": "A valid rating is required."}

Unknown Turn

• Code: 404 Not Found
• Content: {"error": "Turn not found."}