Documentation

Chat & conversations

How conversation memory works in Nimblesite.

Chat & conversations

Every conversation with an agent happens through a single endpoint:

POST /api/v1/chat/{config_id}

You send a message. You get back a response. The platform handles the rest.

Request

{
  "message": "Change my phone number to 0412 345 678"
}
Field Required Notes
message yes The user's message.
conversation_id no UUID returned by an earlier chat response. Reuse it to continue that conversation. Omit it to start a new one.
template_vars no Extra variables for the system prompt template.

Response

{
  "response": "Done — phone updated.",
  "conversation_id": "11111111-1111-1111-1111-111111111111",
  "tool_calls": []
}

The response is the final text from the agent. The tool_calls array is non-empty when the agent wants you to run something (see Tools).

How conversations work

Conversations are how Nimblesite turns a stateless LLM into a stateful agent.

The first time you send chat without conversation_id, we create a Conversation row and return its UUID. From then on, every chat with that conversation_id:

  1. Loads every prior message in that conversation
  2. Hands the full history to the model
  3. Stores the new user message and the new assistant message
  4. Returns the response

You don't store messages. You don't replay history. You don't manage windows or token budgets. Send a conversation_id, and the agent already knows.

Conversation ID conventions

The conversation_id is a NAP-generated UUID. Store it against whatever product object should continue the conversation:

  • Per-user persistent assistant: save the UUID on the user record
  • Per-tab/per-page chat widget: save the UUID in browser state
  • Per-issue support thread: save the UUID on the ticket
  • New conversation: omit the conversation_id field

If two clients share the same conversation_id, they share the same memory. Store different UUIDs when histories must stay separate.

Inspecting a conversation

curl https://api.nimblesite.dev/api/v1/conversations/$CONVERSATION_ID \
  -H "X-API-Key: $NIMBLE_KEY"

Returns the full message history for that conversation, scoped to your tenant. Use this for support, debugging, audit, or building your own chat UI on top of stored history.

What conversation IDs are NOT

  • Not authentication. A conversation ID does not authenticate the user. Auth happens through the X-API-Key header (which scopes to a tenant). Your app is responsible for binding conversations to users in your own user model.
  • Not encryption. Conversation history is stored in plain text in your tenant's rows. If you need encryption at rest, configure it on the database itself.
  • Not free. Long conversations cost more tokens because we send more history. Start new conversations in your product when you want to control cost.