7 Use the Nous Chat API

Use the Nous Chat API to send a question from your own script or application to a Nous workspace. The request runs a Nous conversation with the workspace’s configured model. It can use knowledge and agents that the token owner is allowed to access.

7.1 Get a token and workspace address

Create a personal API token, or ask a workspace admin for a service-account token if an integration needs its own identity. Copy the token when it is shown, and use the Nous address of that workspace. A personal token acts as its owner; a service-account token acts as that account. Neither token grants access to documents or agents beyond its identity’s permissions.

Set these values in your terminal, replacing the placeholders. Keep the token out of source control and shared logs.

NOUS_URL='https://nous.example.com'
NOUS_TOKEN='<paste-your-token>'

curl -sS "$NOUS_URL/api/me" \
  -H "Authorization: Bearer $NOUS_TOKEN"

If /api/me does not return your expected identity, check the token and workspace address before sending a chat request.

7.2 Send your first message

This request starts a conversation with the default agent. message is the question or instruction you want the assistant to answer.

curl -sS "$NOUS_URL/api/chat/send-chat-message" \
  -H "Authorization: Bearer $NOUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarize our onboarding policy",
    "knowledge_search_enabled": true,
    "stream": false
  }'

knowledge_search_enabled: true lets the agent search indexed sources available to the token owner when relevant. It does not force a search. Search also requires an enabled search tool and an eligible knowledge scope. stream: false returns one JSON response, which is easier to use in a first integration.

7.3 Choose request options

Field	What it does	If omitted
`message`	The prompt sent to the assistant. Required.	The request is invalid.
`knowledge_search_enabled`	`true` lets the agent search permitted workspace knowledge when useful; `false` turns off ambient search.	No knowledge search is requested.
`stream`	`false` returns one JSON response; `true` returns JSON objects one line at a time.	`true`: the response is a stream of JSON lines, not one JSON object.
`chat_session_info`	Starts a new conversation. Add `{"persona_id":123}` to choose an accessible agent.	A new conversation uses the default agent when `chat_session_id` is also omitted.
`chat_session_id`	Continues an existing conversation using the ID returned by an earlier response.	A new conversation starts when `chat_session_info` is also omitted.
`include_citations`	`false` removes citation markers from the answer.	`true`: citations are included when available.

Send chat_session_info or chat_session_id, never both in the same request. For everyday chat, start with the first example and add an option only when you need it.

For stream: true, the HTTP content type is text/event-stream, but the body contains newline-delimited JSON rather than data: event frames. Parse one JSON object per line.

7.4 Read the response

With stream: false, the JSON response includes the answer. The first response of a new conversation also includes its chat_session_id. Save that ID and keep using it for later messages; follow-up responses can contain "chat_session_id": null. The following is an excerpt; document objects have more fields in the actual response.

{
  "answer": "The policy requires a first-week check-in. [1]",
  "chat_session_id": "cba35529-7e57-4c57-8f84-0c9733277f5c",
  "message_id": 42,
  "top_documents": [
    {
      "document_id": "onboarding-policy",
      "semantic_identifier": "Onboarding policy"
    }
  ],
  "citation_info": [
    {
      "type": "citation_info",
      "citation_number": 1,
      "document_id": "onboarding-policy"
    }
  ],
  "error_msg": null
}

top_documents lists retrieved sources, and citation_info connects numbered citations to documents. An answer may have no citations if the agent did not retrieve a source. Check error_msg before using answer: a chat request can return HTTP 200 with an error in the response. error_code and error_is_retryable provide more information when that happens.

7.5 Continue the conversation

Use the chat_session_id from the first response for every later message in that conversation. Replace the example ID with the one your first request returned. Do not replace your saved ID with the null value from a follow-up response.

curl -sS "$NOUS_URL/api/chat/send-chat-message" \
  -H "Authorization: Bearer $NOUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What should the manager do next?",
    "chat_session_id": "cba35529-7e57-4c57-8f84-0c9733277f5c",
    "knowledge_search_enabled": true,
    "stream": false
  }'

7.6 Start with another agent

List the agents available to your token, then use an agent ID in the first message of a new conversation:

curl -sS "$NOUS_URL/api/agents?page_size=100" \
  -H "Authorization: Bearer $NOUS_TOKEN"

curl -sS "$NOUS_URL/api/chat/send-chat-message" \
  -H "Authorization: Bearer $NOUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarize our onboarding policy",
    "chat_session_info": {"persona_id": 123},
    "knowledge_search_enabled": true,
    "stream": false
  }'

Replace 123 with an accessible agent’s ID. For later messages to that agent, use the returned chat_session_id instead of chat_session_info.

7.7 If something does not work

Authentication or access fails: confirm the workspace address, token expiry, and the token owner’s access to that workspace and agent. Never send the token to support in a screenshot or message.
The response arrives as JSON lines rather than one JSON object: set "stream":false in the request body.
The answer has no knowledge citations: send "knowledge_search_enabled":true, confirm that the token owner can access the source, and check that the agent has an enabled search tool. The agent may still decide no search is needed. See Knowledge Search for how search scopes work.
The HTTP request succeeds but the answer is unusable: inspect error_msg, error_code, and error_is_retryable in the JSON response before treating it as a successful answer.