Skip to main content

Managing Sessions

In Nexus, sessions are an essential concept. They hold the conversation history between the user and the AI agent. This history allows the LLM to keep context over time, providing more coherent and helpful answers.

Each session can be given a name to help you group or organize them. You can also attach a persona to a session, which customizes the style and tone of the LLM's responses.

If you're integrating Nexus into your own platform , for example, as a customer support tool, you can think of sessions as rooms linked to a specific user in your backend. You handle the user logic, and simply map your users to Nexus sessions.

Some important notes:

  • Sessions always require an AI agent. You cannot delete an agent if there are still sessions attached to it. You'll have to switch the session to another agent.
  • You're free to change the AI agent in a session at any time. This can be useful to pick your best-suited agent based on the conversation flow.
  • Sessions retain the full conversation history, which you can fetch any time. If you want to reset the history, simply delete and recreate the session.

Start a New Session​

POST /chat/session/new

🚨 Do not create a session using a config with user_id of "default".
Make sure the provided agent_id is valid and belongs to the current user.

Payload example:

{
  "name": "New Session",
  "persona_id": 1,
  "agent_id": 2
}

Response example:

{
  "status": "ok",
  "data": {
    "session_id": "52544d1b-5cd6-44f4-96dd-e29e4f5546fa"
  }
}

Update a Session​

PATCH /chat/session/{session_id}

You can update the name or switch to another agent mid-session.

Payload example:

{
  "name": "Updated Session",
  "agent_id": "..."
}

Response example:

{
  "status": "ok",
  "data": {
    "session_id": "52544d1b-5cd6-44f4-96dd-e29e4f5546fa",
    "name": "Updated Session",
    "agent_id": "...",
    "created_at": "2025-05-20T09:05:33.773043"
  }
}

Fetch Session History​

GET /chat/session/{session_id}

Fetches the full conversation history for a session.

ℹī¸ *Note: Messages containing <think> tags contain reasoning output

Response example:

{
    "status": "ok",
    "data": {
        "session_id": "795fbd41-f5d0-4942-b551-e71c987b4be9",
        "name": "Session Name",
        "created_at": "2025-07-07T22:13:11.650709",
        "persona_id": 1,
        "agent_id": "2242a465-ed26-46c4-afb2-0c5c09ca2b5f",
        "messages": [
            {
                "role": "user",
                "content": "Test",
                "type": null,
                "status": null,
                "run_id": null,
                "artifacts": null,
                "suggestions": null
            },
            {
                "role": "assistant",
                "content": "Please let me know what specific task or query you would like to test, and I'll be happy to assist you.",
                "type": "chat",
                "status": "ok",
                "run_id": "",
                "artifacts": [],
                "suggestions": null
            }
        ]
    }
}

Delete a Session​

DELETE /chat/session/{session_id}

Deletes the session and its history.

Response example:

{
  "status": "ok"
}

List All Sessions​

GET /chat/session

Lists all active sessions for the user.

Response example:

{
  "status": "ok",
  "data": {
    "sessions": [
      {
        "name": "Session B",
        "created_at": "2025-04-11T11:59:57.637190",
        "session_id": "056edc7f-6afe-46c3-8d91-d202fbefc85c",
        "user_id": "0x00..",
        "persona_id": 1
      }
    ]
  }
}