Twins

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

Retrieve individual digital twin personas from static groups.

List Static Group Twins

GET/v1/workspaces/{workspace_id}/static-groups/{group_key}/twins

Path Parameters

Parameter	Type	Required	Description
workspace_id	string	Yes
group_key	string	Yes

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-based)
size	integer	20	Number of elements per page
order	string	—	Sort order by name
twinIds	string	—	Comma-separated twin IDs to filter for
language	string	—	Filter by language

Response

FieldTypeDescription

dataarray<object>List of twins for this page

idstringUnique identifier

createdAtstringTimestamp when the record was created

updatedAtstringTimestamp when the record was last updated

createdByUserIdobjectID of the user who created this record

targetAudienceIdobjectTarget audience ID (either this or staticGroupKey must be set)

staticGroupKeyobjectKey of the associated static group (either this or targetAudienceId must be set)

subjectIdstringID of the subject this twin is based on

namestringFull name of the digital twin

languagestringLanguage code: 'en' or 'de'

titleobjectDescriptive title for the digital twin

ageobjectAge of the digital twin

genderobjectGender of the digital twin

locationobjectLocation of the digital twin

jobTitleobjectJob title of the digital twin

selfDescriptionobjectSelf-description of the digital twin from survey responses

shortBioobjectShort third-person blurb shown above the persona overview (1-2 sentences, ~40-60 words). Distinct from selfDescription which is first-person.

interestsAndPreferencesobjectFirst-person paragraph (~80-150 words) about hobbies, brands consumed, media habits, lifestyle.

uniqueTraitsobjectFirst-person paragraph (~80-150 words) describing the traits that distinguish this persona from typical peers.

demographicsobjectStructured demographic attributes derived from the persona's survey answers. Persisted at twin-creation time. Absent keys hide the corresponding UI row. Frontend resolves labels via i18n key brand_hub.digital_twin.detail.demographics.<snake_case_key>.

psychographicsobjectStructured psychographic attributes derived from the persona's survey answers. Persisted at twin-creation time. Absent keys hide the corresponding UI row. Frontend resolves labels via i18n key brand_hub.digital_twin.detail.psychographics.<snake_case_key>.

activebooleanTrue if the twin is active and usable — can be chatted with, is used for reactions, etc.

_linksobjectHATEOAS links (e.g., avatarUrl)

pageobjectPagination metadata.

sizeintegerNumber of elements per page

totalElementsintegerTotal number of matching elements

totalPagesintegerTotal number of pages

currentPageintegerCurrent page number (1-based)

Example

cURL

curl "https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/{workspace_id}/static-groups/{group_key}/twins" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

response = requests.get(
    f"https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/{workspace_id}/static-groups/{group_key}/twins",
    headers={"Authorization": f"Bearer {token}"},
).json()

Node.js

const response = await fetch(
  `https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/${workspaceId}/static-groups/${groupKey}/twins`,
  { headers: { Authorization: `Bearer ${token}` } }
).then((r) => r.json());

Go

req, _ := http.NewRequest("GET", "https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/"+workspaceID+"/static-groups/"+groupKey+"/twins", nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "createdByUserId": "12345",
      "targetAudienceId": "aud_12345",
      "staticGroupKey": "millennials",
      "subjectId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Jens Bauer",
      "language": "en",
      "title": "Tech-Savvy Millennial",
      "age": 28,
      "gender": "Male",
      "location": "Berlin, Germany",
      "jobTitle": "Software Engineer",
      "selfDescription": "I'm a tech enthusiast who loves innovation and problem-solving.",
      "shortBio": "Sarah is a marketing director with 10+ years of experience in the fashion industry.",
      "interestsAndPreferences": "I enjoy gardening and taking walks in the countryside. On weekends I usually meet friends for brunch and follow a few independent fashion designers on Instagram.",
      "uniqueTraits": "I'm a 38-year-old married woman living alone in a quiet country village, which is unusual for my age group. I value independence over the social rhythms most of my peers prefer.",
      "demographics": {},
      "psychographics": {},
      "active": true,
      "_links": {}
    }
  ],
  "page": {
    "size": 0,
    "totalElements": 0,
    "totalPages": 0,
    "currentPage": 0
  }
}

Chat With Twin

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

Path Parameters

Parameter	Type	Required	Description
workspace_id	string	Yes
twin_id	string	Yes

Request Body

FieldTypeRequiredDescription

messagesarray<object>YesConversation history (at least one message required, last message must be from user)

rolestringYesRole: 'user' or 'assistant'

contentstringYesMessage content

attachmentsobjectNoList of file IDs to attach to this message (user messages only)

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:

{}

List Twins

GET/v1/workspaces/{workspace_id}/twins

Path Parameters

Parameter	Type	Required	Description
workspace_id	string	Yes

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-based)
size	integer	20	Number of elements per page
sort	string	—	Sort field: 'name' or 'createdAt'
order	string	—	Sort order
targetAudienceId	string	—	Filter by target audience
name	string	—	Filter by name prefix (case-insensitive)

Response

FieldTypeDescription

dataarray<object>List of twins for this page

idstringUnique identifier

createdAtstringTimestamp when the record was created

updatedAtstringTimestamp when the record was last updated

createdByUserIdobjectID of the user who created this record

targetAudienceIdobjectTarget audience ID (either this or staticGroupKey must be set)

staticGroupKeyobjectKey of the associated static group (either this or targetAudienceId must be set)

subjectIdstringID of the subject this twin is based on

namestringFull name of the digital twin

languagestringLanguage code: 'en' or 'de'

titleobjectDescriptive title for the digital twin

ageobjectAge of the digital twin

genderobjectGender of the digital twin

locationobjectLocation of the digital twin

jobTitleobjectJob title of the digital twin

selfDescriptionobjectSelf-description of the digital twin from survey responses

shortBioobjectShort third-person blurb shown above the persona overview (1-2 sentences, ~40-60 words). Distinct from selfDescription which is first-person.

interestsAndPreferencesobjectFirst-person paragraph (~80-150 words) about hobbies, brands consumed, media habits, lifestyle.

uniqueTraitsobjectFirst-person paragraph (~80-150 words) describing the traits that distinguish this persona from typical peers.

demographicsobjectStructured demographic attributes derived from the persona's survey answers. Persisted at twin-creation time. Absent keys hide the corresponding UI row. Frontend resolves labels via i18n key brand_hub.digital_twin.detail.demographics.<snake_case_key>.

psychographicsobjectStructured psychographic attributes derived from the persona's survey answers. Persisted at twin-creation time. Absent keys hide the corresponding UI row. Frontend resolves labels via i18n key brand_hub.digital_twin.detail.psychographics.<snake_case_key>.

activebooleanTrue if the twin is active and usable — can be chatted with, is used for reactions, etc.

_linksobjectHATEOAS links (e.g., avatarUrl)

pageobjectPagination metadata.

sizeintegerNumber of elements per page

totalElementsintegerTotal number of matching elements

totalPagesintegerTotal number of pages

currentPageintegerCurrent page number (1-based)

Example

cURL

curl "https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/{workspace_id}/twins" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

response = requests.get(
    f"https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/{workspace_id}/twins",
    headers={"Authorization": f"Bearer {token}"},
).json()

Node.js

const response = await fetch(
  `https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/${workspaceId}/twins`,
  { headers: { Authorization: `Bearer ${token}` } }
).then((r) => r.json());

Go

req, _ := http.NewRequest("GET", "https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/"+workspaceID+"/twins", nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "createdByUserId": "12345",
      "targetAudienceId": "aud_12345",
      "staticGroupKey": "millennials",
      "subjectId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Jens Bauer",
      "language": "en",
      "title": "Tech-Savvy Millennial",
      "age": 28,
      "gender": "Male",
      "location": "Berlin, Germany",
      "jobTitle": "Software Engineer",
      "selfDescription": "I'm a tech enthusiast who loves innovation and problem-solving.",
      "shortBio": "Sarah is a marketing director with 10+ years of experience in the fashion industry.",
      "interestsAndPreferences": "I enjoy gardening and taking walks in the countryside. On weekends I usually meet friends for brunch and follow a few independent fashion designers on Instagram.",
      "uniqueTraits": "I'm a 38-year-old married woman living alone in a quiet country village, which is unusual for my age group. I value independence over the social rhythms most of my peers prefer.",
      "demographics": {},
      "psychographics": {},
      "active": true,
      "_links": {}
    }
  ],
  "page": {
    "size": 0,
    "totalElements": 0,
    "totalPages": 0,
    "currentPage": 0
  }
}

Get Twin

GET/v1/workspaces/{workspace_id}/twins/{twin_id}

Path Parameters

Parameter	Type	Required	Description
workspace_id	string	Yes
twin_id	string	Yes

Response

FieldTypeDescription

idstringUnique identifier

createdAtstringTimestamp when the record was created

updatedAtstringTimestamp when the record was last updated

createdByUserIdobjectID of the user who created this record

targetAudienceIdobjectTarget audience ID (either this or staticGroupKey must be set)

staticGroupKeyobjectKey of the associated static group (either this or targetAudienceId must be set)

subjectIdstringID of the subject this twin is based on

namestringFull name of the digital twin

languagestringLanguage code: 'en' or 'de'

titleobjectDescriptive title for the digital twin

ageobjectAge of the digital twin

genderobjectGender of the digital twin

locationobjectLocation of the digital twin

jobTitleobjectJob title of the digital twin

selfDescriptionobjectSelf-description of the digital twin from survey responses

shortBioobjectShort third-person blurb shown above the persona overview (1-2 sentences, ~40-60 words). Distinct from selfDescription which is first-person.

interestsAndPreferencesobjectFirst-person paragraph (~80-150 words) about hobbies, brands consumed, media habits, lifestyle.

uniqueTraitsobjectFirst-person paragraph (~80-150 words) describing the traits that distinguish this persona from typical peers.

demographicsobjectStructured demographic attributes derived from the persona's survey answers. Persisted at twin-creation time. Absent keys hide the corresponding UI row. Frontend resolves labels via i18n key brand_hub.digital_twin.detail.demographics.<snake_case_key>.

psychographicsobjectStructured psychographic attributes derived from the persona's survey answers. Persisted at twin-creation time. Absent keys hide the corresponding UI row. Frontend resolves labels via i18n key brand_hub.digital_twin.detail.psychographics.<snake_case_key>.

activebooleanTrue if the twin is active and usable — can be chatted with, is used for reactions, etc.

_linksobjectHATEOAS links (e.g., avatarUrl)

Example

cURL

curl "https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/{workspace_id}/twins/{twin_id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

response = requests.get(
    f"https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/{workspace_id}/twins/{twin_id}",
    headers={"Authorization": f"Bearer {token}"},
).json()

Node.js

const response = await fetch(
  `https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/${workspaceId}/twins/${twinId}`,
  { headers: { Authorization: `Bearer ${token}` } }
).then((r) => r.json());

Go

req, _ := http.NewRequest("GET", "https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/"+workspaceID+"/twins/"+twinID+"", nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "createdByUserId": "12345",
  "targetAudienceId": "aud_12345",
  "staticGroupKey": "millennials",
  "subjectId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Jens Bauer",
  "language": "en",
  "title": "Tech-Savvy Millennial",
  "age": 28,
  "gender": "Male",
  "location": "Berlin, Germany",
  "jobTitle": "Software Engineer",
  "selfDescription": "I'm a tech enthusiast who loves innovation and problem-solving.",
  "shortBio": "Sarah is a marketing director with 10+ years of experience in the fashion industry.",
  "interestsAndPreferences": "I enjoy gardening and taking walks in the countryside. On weekends I usually meet friends for brunch and follow a few independent fashion designers on Instagram.",
  "uniqueTraits": "I'm a 38-year-old married woman living alone in a quiet country village, which is unusual for my age group. I value independence over the social rhythms most of my peers prefer.",
  "demographics": {},
  "psychographics": {},
  "active": true,
  "_links": {}
}