Skip to main content

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

List all twins in a static group with pagination.

Optionally filter by specific twin IDs using the twinIds query parameter. Sorted by name in the specified order.

Requires authentication.

Path Parameters​

ParameterTypeRequiredDescription
group_keystringYesThe static group key (e.g., gen_z, millennials)

Query Parameters​

ParameterTypeDefaultDescription
pageinteger1Page number (1-based)
sizeinteger20Number of elements per page
orderstring—Sort order by name
twinIdsstring—Comma-separated list of twin IDs to filter for

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
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
_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 "https://app.neuroflash.com/api/digital-twin-service/v1/workspaces/{workspace_id}/static-groups/{group_key}/twins" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

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",
      "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.",
      "_links": {}
    }
  ],
  "page": {
    "size": 0,
    "totalElements": 0,
    "totalPages": 0,
    "currentPage": 0
  }
}

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​

ParameterTypeRequiredDescription
workspace_idstringYes
twin_idstringYes

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 -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": {}
  }'

Response:

{}

Get Twin​

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

Get a single digital twin by ID.

Returns global twins (static groups) or workspace-specific twins that belong to the user's workspace.

Requires authentication.

Path Parameters​

ParameterTypeRequiredDescription
workspace_idstringYesThe workspace ID
twin_idstringYesThe twin ID to retrieve

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
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
_linksobjectHATEOAS links (e.g., avatarUrl)

Example​

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

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",
  "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.",
  "_links": {}
}