Chat

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

Chat with an individual digital twin. The twin responds based on its demographic profile, personality, and perspective.

Chat With Twin

POST/v1/workspaces/{workspace_id}/twins/{twin_id}/chat-completions

Chat with a digital twin with conversation context.

Messages Format:

• User messages: Standard format with role="user" and content
• Assistant messages: Previous twin responses for conversation context

Response Format:

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

Important: useVerbalizedSampling and responseFormat are mutually exclusive.

---

Example 1: Single Turn, Default Response Format

Request:

{
  "messages": [
    {"role": "user", "content": "What do you think about remote work?"}
  ]
}

Response:

{
  "answer": "I believe remote work offers great flexibility...",
  "reason": "As someone who values work-life balance, I appreciate..."
}

---

Example 2: Multi-turn Conversation, Default Response Format

Request:

{
  "messages": [
    {"role": "user", "content": "What do you think about remote work?"},
    {"role": "assistant", "content": "I believe remote work offers great flexibility and helps with work-life balance."},
    {"role": "user", "content": "What challenges do you see?"}
  ]
}

Response:

{
  "answer": "The main challenge is maintaining team collaboration and spontaneous interactions that happen naturally in an office.",
  "reason": "Based on my previous point about flexibility, I recognize there's a tradeoff with in-person connection."
}

---

Example 3: Single Turn, Custom Response Format

Request:

{
  "messages": [
    {"role": "user", "content": "Rate your enthusiasm for AI 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:

{
  "rating": 9,
  "explanation": "I'm highly enthusiastic about AI's potential to solve complex problems..."
}

---

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

Path Parameters

Parameter	Type	Required	Description
workspace_id	string	Yes
twin_id	string	Yes

Request Body

FieldTypeRequiredDescription

messagesarray<object>YesConversation history

rolestringYesRole: 'user' or 'assistant'

contentstringYesMessage content

responseFormatobjectNoStructured output format using JSON schema. If null, uses default schema with 'answer' and 'reason' fields.

temperatureobjectNoSampling temperature for response generation

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

useVerbalizedSamplingobjectNoGenerate 5 probability-weighted response options (tau=0.10). Mutually exclusive with custom responseFormat.

Example

cURL

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

Python

import requests

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

Node.js

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

Go

body, _ := json.Marshal(map[string]any{
		"messages": []any{},
		"responseFormat": map[string]any{},
		"temperature": 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+"/twins/"+twinID+"/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:

{}