Persistent Conversations

This guide shows you how to use the conversations API to run multi-turn chat sessions without re-sending the full message history on every request.

What you'll build

By the end of this guide, you will:

• Create a persistent conversation
• Send multi-turn messages without re-sending history
• Retrieve the conversation and its full message history
• Delete the conversation when done

Prerequisites

• A neuroflash account with API access
• Your client_id and client_secret (see Authentication)

Step 1: Authenticate

cURL

curl -X POST https://id.neuroflash.com/oauth/v2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=openid"

Python

import requests

BASE_URL = "https://app.neuroflash.com/api"

token = requests.post(
    "https://id.neuroflash.com/oauth/v2/token",
    data={
        "grant_type": "client_credentials",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "scope": "openid",
    },
).json()["access_token"]

headers = {"Authorization": f"Bearer {token}"}

Node.js

const BASE_URL = "https://app.neuroflash.com/api";

const { access_token } = await fetch(
  "https://id.neuroflash.com/oauth/v2/token",
  {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_id: "YOUR_CLIENT_ID",
      client_secret: "YOUR_CLIENT_SECRET",
      scope: "openid",
    }),
  }
).then((r) => r.json());

const headers = { Authorization: `Bearer ${access_token}` };

Go

data := url.Values{
    "grant_type":    {"client_credentials"},
    "client_id":     {"YOUR_CLIENT_ID"},
    "client_secret": {"YOUR_CLIENT_SECRET"},
    "scope":         {"openid"},
}

resp, _ := http.Post(
    "https://id.neuroflash.com/oauth/v2/token",
    "application/x-www-form-urlencoded",
    strings.NewReader(data.Encode()),
)
defer resp.Body.Close()

var authResult struct{ AccessToken string `json:"access_token"` }
json.NewDecoder(resp.Body).Decode(&authResult)
token := authResult.AccessToken

Step 2: Get Your Workspace

cURL

curl "https://app.neuroflash.com/api/workspace-service/v1/workspaces" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

workspaces = requests.get(
    f"{BASE_URL}/workspace-service/v1/workspaces",
    headers=headers,
).json()
workspace_id = workspaces["_embedded"]["workspaces"][0]["id"]

Node.js

const workspaces = await fetch(
  `${BASE_URL}/workspace-service/v1/workspaces`,
  { headers }
).then((r) => r.json());
const workspaceId = workspaces._embedded.workspaces[0].id;

Go

req, _ := http.NewRequest("GET", baseURL+"/workspace-service/v1/workspaces", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
// parse JSON and extract _embedded.workspaces[0].id into workspaceID

Step 3: Create a Conversation

Note: workspace_id goes in the JSON body for POST, not as a header.

cURL

curl -X POST "https://app.neuroflash.com/api/ds-prototypes/conversations" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "workspace_id": "YOUR_WORKSPACE_ID" }'

Python

conv = requests.post(
    f"{BASE_URL}/ds-prototypes/conversations",
    headers={**headers, "Content-Type": "application/json"},
    json={"workspace_id": workspace_id},
).json()
conversation_id = conv["uuid"]

Node.js

const conv = await fetch(`${BASE_URL}/ds-prototypes/conversations`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ workspace_id: workspaceId }),
}).then((r) => r.json());
const conversationId = conv.uuid;

Go

body, _ := json.Marshal(map[string]string{"workspace_id": workspaceID})
req, _ := http.NewRequest("POST", baseURL+"/ds-prototypes/conversations", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Response:

{
  "uuid": "ebb3fbeb-69ed-41e9-bcb5-1ec8a643566e",
  "workspace_id": "b481b98b-a7ed-4d72-a1f2-8b2ae3a57854",
  "created_at": "2026-04-08T15:44:47.383172"
}

Step 4: Send a Message

The conversation service stores your message history — you do not need to re-send previous turns. Each request only needs to contain the new user message.

cURL

curl -X POST "https://app.neuroflash.com/api/ds-prototypes/conversations/{uuid}/chat/completions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "messages": [{ "role": "user", "content": "What makes neuroflash unique?" }] }'

Python

reply = requests.post(
    f"{BASE_URL}/ds-prototypes/conversations/{conversation_id}/chat/completions",
    headers={**headers, "Content-Type": "application/json"},
    json={"messages": [{"role": "user", "content": "What makes neuroflash unique?"}]},
).json()

Node.js

const reply = await fetch(
  `${BASE_URL}/ds-prototypes/conversations/${conversationId}/chat/completions`,
  {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({ messages: [{ role: "user", content: "What makes neuroflash unique?" }] }),
  }
).then((r) => r.json());

Go

body, _ := json.Marshal(map[string]any{
    "messages": []map[string]string{
        {"role": "user", "content": "What makes neuroflash unique?"},
    },
})
req, _ := http.NewRequest("POST", baseURL+"/ds-prototypes/conversations/"+conversationID+"/chat/completions", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

Response:

{
  "id": "gen-1775000000-AbCdEfGh",
  "object": "chat.completion",
  "model": "openai/gpt-4.1-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Neuroflash is unique because it combines brand-aware AI content generation with European data privacy standards and multi-language support."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 28, "total_tokens": 40, "words_used": 22 }
}

Step 5: Send a Follow-up

Send another message to the same conversation — no need to re-send history. The context from step 4 is retained on the server.

cURL

curl -X POST "https://app.neuroflash.com/api/ds-prototypes/conversations/{uuid}/chat/completions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "messages": [{ "role": "user", "content": "Can you give me an example?" }] }'

Python

followup = requests.post(
    f"{BASE_URL}/ds-prototypes/conversations/{conversation_id}/chat/completions",
    headers={**headers, "Content-Type": "application/json"},
    json={"messages": [{"role": "user", "content": "Can you give me an example?"}]},
).json()

Node.js

const followup = await fetch(
  `${BASE_URL}/ds-prototypes/conversations/${conversationId}/chat/completions`,
  {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({ messages: [{ role: "user", content: "Can you give me an example?" }] }),
  }
).then((r) => r.json());

Go

body, _ := json.Marshal(map[string]any{
    "messages": []map[string]string{
        {"role": "user", "content": "Can you give me an example?"},
    },
})
// Same endpoint and headers as Step 4.

Step 6: Retrieve the Conversation

workspace_id required on GET and DELETE

The conversations service enforces workspace-scoped ownership. The workspace_id query parameter is required on all GET and DELETE requests. Omitting it or using the wrong workspace returns 403 Forbidden.

cURL

curl "https://app.neuroflash.com/api/ds-prototypes/conversations/{uuid}?workspace_id=YOUR_WORKSPACE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

conv = requests.get(
    f"{BASE_URL}/ds-prototypes/conversations/{conversation_id}",
    headers=headers,
    params={"workspace_id": workspace_id},
).json()

Node.js

const conv = await fetch(
  `${BASE_URL}/ds-prototypes/conversations/${conversationId}?workspace_id=${workspaceId}`,
  { headers }
).then((r) => r.json());

Go

u := fmt.Sprintf("%s/ds-prototypes/conversations/%s?workspace_id=%s", baseURL, conversationID, workspaceID)
req, _ := http.NewRequest("GET", u, nil)
req.Header.Set("Authorization", "Bearer "+token)

Step 7: Get Message History

cURL

curl "https://app.neuroflash.com/api/ds-prototypes/conversations/{uuid}/messages?workspace_id=YOUR_WORKSPACE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

history = requests.get(
    f"{BASE_URL}/ds-prototypes/conversations/{conversation_id}/messages",
    headers=headers,
    params={"workspace_id": workspace_id},
).json()

Node.js

const history = await fetch(
  `${BASE_URL}/ds-prototypes/conversations/${conversationId}/messages?workspace_id=${workspaceId}`,
  { headers }
).then((r) => r.json());

Go

u := fmt.Sprintf("%s/ds-prototypes/conversations/%s/messages?workspace_id=%s", baseURL, conversationID, workspaceID)
req, _ := http.NewRequest("GET", u, nil)
req.Header.Set("Authorization", "Bearer "+token)

Response:

{
  "messages": [
    { "role": "user", "content": "What makes neuroflash unique?" },
    { "role": "assistant", "content": "Neuroflash is unique due to..." }
  ],
  "next_cursor": null
}

Step 8: Delete the Conversation

cURL

curl -X DELETE "https://app.neuroflash.com/api/ds-prototypes/conversations/{uuid}?workspace_id=YOUR_WORKSPACE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

requests.delete(
    f"{BASE_URL}/ds-prototypes/conversations/{conversation_id}",
    headers=headers,
    params={"workspace_id": workspace_id},
)

Node.js

await fetch(
  `${BASE_URL}/ds-prototypes/conversations/${conversationId}?workspace_id=${workspaceId}`,
  { method: "DELETE", headers }
);

Go

u := fmt.Sprintf("%s/ds-prototypes/conversations/%s?workspace_id=%s", baseURL, conversationID, workspaceID)
req, _ := http.NewRequest("DELETE", u, nil)
req.Header.Set("Authorization", "Bearer "+token)

Next Steps

• Chat Completions reference
• Brand Voice Pipeline guide