Group Chat

Base URL: https://app.neuroflash.com/api/digital-twin-service

Ask multiple digital twins the same question and get aggregated opinions with individual responses.

Chat With Twin Group

POST/v1/workspaces/{workspace_id}/twin-group-chat-completions

Chat with multiple digital twins in parallel with conversation context.

Messages Format:

• User messages: Standard format with role="user" and content
• Assistant messages: Must contain the complete group response as JSON string:

  {
    "summary": "Group summary from previous turn",
    "twinResponses": {
      "twin-id-1": {"answer": "...", "reason": "..."},
      "twin-id-2": {"answer": "...", "reason": "..."}
    }
  }

  Note: When parsing conversation history, twinResponses values can be dict or string - dicts are serialized to JSON strings for individual twin context. When generating new responses, the structure follows the current responseFormat (default: answer/reason, or custom JSON schema).

Response Format:

• Without responseFormat: Each twin returns {"answer": "...", "reason": "..."}
• With responseFormat: Each twin returns structure matching your custom JSON schema
  • type must be "json_schema"
  • schema must not be empty

Important: useVerbalizedSampling and responseFormat are mutually exclusive.

Processing:

• Each twin receives conversation history with only their individual responses extracted from twinResponses
• All twins are queried in parallel with their personalized conversation history
• Individual responses are aggregated and summarized into the group response format

---

Example 1: Single Turn, Default Response Format

Request:

{
  "twinIds": ["twin-1", "twin-2"],
  "messages": [
    {"role": "user", "content": "What do you think about remote work?"}
  ]
}

Response:

{
  "summary": "Mixed views on remote work, with one twin enthusiastic about flexibility and another concerned about collaboration challenges.",
  "twinResponses": {
    "twin-1": {
      "answer": "I believe remote work offers great flexibility and work-life balance.",
      "reason": "It allows me to manage my time more effectively and avoid commuting."
    },
    "twin-2": {
      "answer": "Remote work has both benefits and drawbacks.",
      "reason": "While I appreciate the flexibility, I miss the spontaneous interactions with colleagues."
    }
  }
}

---

Example 2: Multi-turn Conversation, Default Response Format

Request:

{
  "twinIds": ["twin-1", "twin-2"],
  "messages": [
    {"role": "user", "content": "What do you think about remote work?"},
    {"role": "assistant", "content": "{\"summary\": \"Mixed views on remote work.\", \"twinResponses\": {\"twin-1\": {\"answer\": \"I love it!\", \"reason\": \"More flexible...\"}, \"twin-2\": {\"answer\": \"It's challenging.\", \"reason\": \"Miss collaboration...\"}}}"},
    {"role": "user", "content": "How would you improve it?"}
  ]
}

Response:

{
  "summary": "The group suggests improvements like better video tools, scheduled social time, and clearer communication practices.",
  "twinResponses": {
    "twin-1": {
      "answer": "Better video conferencing tools and virtual team activities.",
      "reason": "Would help maintain team connection..."
    },
    "twin-2": {
      "answer": "More structured communication and regular check-ins.",
      "reason": "Clear expectations help overcome the challenges..."
    }
  }
}

---

Example 3: Single Turn, Custom Response Format

Request:

{
  "twinIds": ["twin-1", "twin-2"],
  "messages": [
    {"role": "user", "content": "Rate your enthusiasm for remote work on a scale of 1-10"}
  ],
  "responseFormat": {
    "type": "json_schema",
    "json_schema": {
      "name": "enthusiasm_rating",
      "schema": {
        "type": "object",
        "properties": {
          "rating": {"type": "number", "minimum": 1, "maximum": 10},
          "explanation": {"type": "string"}
        },
        "required": ["rating", "explanation"],
        "additionalProperties": false
      }
    }
  },
  "useVerbalizedSampling": false
}

Response:

{
  "summary": "The group shows varied enthusiasm for remote work, with ratings ranging from 7 to 9, highlighting both flexibility benefits and collaboration concerns.",
  "twinResponses": {
    "twin-1": {
      "rating": 9,
      "explanation": "I highly value the flexibility and work-life balance remote work provides."
    },
    "twin-2": {
      "rating": 7,
      "explanation": "It's mostly positive, though I do miss some aspects of in-person collaboration."
    }
  }
}

---

Requires authentication via x-gateway-token header (or x-local-* headers in local dev).

Path Parameters

Parameter	Type	Required	Description
workspace_id	string	Yes

Request Body

FieldTypeRequiredDescription

twinIdsarray<string>YesList of twin IDs to query (max 20)

messagesarray<object>YesConversation history

rolestringYesRole: 'user' or 'assistant'

contentstringYesMessage content

responseFormatobjectNoStructured output format for individual twin responses. If null, uses default schema with 'answer' and 'reason' fields.

temperatureobjectNoSampling temperature for response generation

runRarobjectNoEnable Rephrase and Respond for question robustness

useWebSearchobjectNoWeb search mode: 'never', 'auto', or 'always'

useVerbalizedSamplingobjectNoGenerate 5 probability-weighted response options per twin. Mutually exclusive with custom responseFormat.

Response

FieldTypeDescription

summarystringLLM-generated summary of all twin responses

twinResponsesobjectDictionary mapping twin IDs to their responses

Example

cURL

curl -X POST "https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/{workspace_id}/twin-group-chat-completions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "twinIds": [],
      "messages": [],
      "responseFormat": {},
      "temperature": {},
      "runRar": {},
      "useWebSearch": {},
      "useVerbalizedSampling": {}
  }'

Python

import requests

response = requests.post(
    f"https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/{workspace_id}/twin-group-chat-completions",
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
    json={
        "twinIds": [],
        "messages": [],
        "responseFormat": {},
        "temperature": {},
        "runRar": {},
        "useWebSearch": {},
        "useVerbalizedSampling": {}
    },
).json()

Node.js

const response = await fetch(
  `https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/${workspaceId}/twin-group-chat-completions`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
          "twinIds": [],
          "messages": [],
          "responseFormat": {},
          "temperature": {},
          "runRar": {},
          "useWebSearch": {},
          "useVerbalizedSampling": {}
    }),
  }
).then((r) => r.json());

Go

body, _ := json.Marshal(map[string]any{
		"twinIds": []any{},
		"messages": []any{},
		"responseFormat": map[string]any{},
		"temperature": map[string]any{},
		"runRar": map[string]any{},
		"useWebSearch": map[string]any{},
		"useVerbalizedSampling": map[string]any{},
	})

req, _ := http.NewRequest("POST", "https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/"+workspaceID+"/twin-group-chat-completions", 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:

{
  "summary": "string",
  "twinResponses": {}
}

Get Twin Group Opinions

POST/v1/workspaces/{workspace_id}/twin-group-chat-opinions

Get opinions from multiple digital twins on a single question (simplified endpoint).

This is a streamlined version of twin-group-chat-completions that:

• Takes a single question instead of full conversation history
• Uses default settings (RaR=true, webSearch=auto, verbalizedSampling=true)
• Returns aggregated response with summary + individual twin responses

Response Format:

• Without responseFormat: Each twin returns {"answer": "...", "reason": "..."}
• With responseFormat: Each twin returns structure matching your custom JSON schema
  • type must be "json_schema"
  • schema must not be empty

Important: Custom responseFormat automatically disables useVerbalizedSampling.

---

Example 1: Default Response Format (No responseFormat)

Request:

{
  "twinIds": ["twin-id-1", "twin-id-2", "twin-id-3"],
  "question": "What do you think about remote work?"
}

Response:

{
  "summary": "The group shows generally positive views on remote work, emphasizing flexibility and work-life balance, though some note challenges with collaboration.",
  "twinResponses": {
    "twin-id-1": {
      "answer": "I'm very supportive of remote work...",
      "reason": "It allows for better work-life balance..."
    },
    "twin-id-2": {
      "answer": "Remote work has both pros and cons...",
      "reason": "While it offers flexibility, I miss in-person collaboration..."
    },
    "twin-id-3": {
      "answer": "I prefer a hybrid approach...",
      "reason": "Combining remote and office work gives the best of both worlds..."
    }
  }
}

---

Example 2: Custom Response Format (With responseFormat)

Request:

{
  "twinIds": ["twin-id-1", "twin-id-2"],
  "question": "Rate your enthusiasm for remote work on a scale of 1-10",
  "responseFormat": {
    "type": "json_schema",
    "json_schema": {
      "name": "enthusiasm_rating",
      "schema": {
        "type": "object",
        "properties": {
          "rating": {"type": "number", "minimum": 1, "maximum": 10},
          "explanation": {"type": "string"}
        },
        "required": ["rating", "explanation"],
        "additionalProperties": false
      }
    }
  }
}

Response:

{
  "summary": "The group shows high enthusiasm for remote work, with ratings averaging 8.5 out of 10, citing flexibility and work-life balance as key factors.",
  "twinResponses": {
    "twin-id-1": {
      "rating": 9,
      "explanation": "I highly value the flexibility and work-life balance remote work provides."
    },
    "twin-id-2": {
      "rating": 8,
      "explanation": "It's great overall, though I do miss some aspects of in-person collaboration."
    }
  }
}

---

Requires authentication via x-gateway-token header (or x-local-* headers in local dev).

Path Parameters

Parameter	Type	Required	Description
workspace_id	string	Yes

Request Body

FieldTypeRequiredDescription

twinIdsarray<string>YesList of twin IDs to query (max 20)

questionstringYesQuestion to ask all twins

responseFormatobjectNoStructured output format for individual twin responses. If null, uses default schema with 'answer' and 'reason' fields.

Response

FieldTypeDescription

summarystringLLM-generated summary of all twin responses

twinResponsesobjectDictionary mapping twin IDs to their responses

Example

cURL

curl -X POST "https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/{workspace_id}/twin-group-chat-opinions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "twinIds": [],
      "question": "string",
      "responseFormat": {}
  }'

Python

import requests

response = requests.post(
    f"https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/{workspace_id}/twin-group-chat-opinions",
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
    json={
        "twinIds": [],
        "question": "string",
        "responseFormat": {}
    },
).json()

Node.js

const response = await fetch(
  `https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/${workspaceId}/twin-group-chat-opinions`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
          "twinIds": [],
          "question": "string",
          "responseFormat": {}
    }),
  }
).then((r) => r.json());

Go

body, _ := json.Marshal(map[string]any{
		"twinIds": []any{},
		"question": "string",
		"responseFormat": map[string]any{},
	})

req, _ := http.NewRequest("POST", "https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/"+workspaceID+"/twin-group-chat-opinions", 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:

{
  "summary": "string",
  "twinResponses": {}
}