{"openapi":"3.1.0","info":{"title":"Digital Twin Service","description":"Service for managing digital twins, surveys, subjects, and static groups","version":"1.0.0"},"paths":{"/v1/static-groups":{"get":{"tags":["Static groups"],"summary":"List Static Groups","description":"Get available static groups, optionally filtered by language.\n\nReturns a list of predefined demographic and psychographic groups with their unique keys,\nlabels, and descriptions.\n\nQuery Parameters:\n- language: Optional language code to filter groups ('en' or 'de').\n           If not provided, returns all groups including language-agnostic ones.\n\nRequires authentication.","operationId":"list_static_groups_v1_static_groups_get","parameters":[{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"enum":["en","de"],"type":"string"},{"type":"null"}],"description":"Filter by language: 'en' or 'de'","title":"Language"},"description":"Filter by language: 'en' or 'de'"},{"name":"x-gateway-token","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Gateway-Token"}},{"name":"x-local-workspaceid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspaceid"}},{"name":"x-local-customerid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Customerid"}},{"name":"x-local-userid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Userid"}},{"name":"x-local-roles","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Roles"}},{"name":"x-local-workspacerole","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspacerole"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StaticGroup"},"title":"Response List Static Groups V1 Static Groups Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/v1/workspaces/{workspace_id}/reactions":{"get":{"tags":["Reactions"],"summary":"List Reactions","description":"List reactions with pagination.\n\nUse basedOn=staticGroup to return static group reactions.\nUse basedOn=targetAudience to return reactions for target audiences.\n\nOnly returns reactions whose language matches the lead twin's language, filtering out\nlegacy mismatches where a twin was assigned reactions in a different language.\n\nSorted by created_at in the specified order. Optionally filtered by language and type.\n\nRequires authentication.","operationId":"list_reactions_v1_workspaces__workspace_id__reactions_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based)","default":1,"title":"Page"},"description":"Page number (1-based)"},{"name":"size","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":0,"description":"Number of elements per page","default":20,"title":"Size"},"description":"Number of elements per page"},{"name":"order","in":"query","required":false,"schema":{"$ref":"#/components/schemas/modules__reaction__router__SortOrder","description":"Sort order by createdAt","default":"desc"},"description":"Sort order by createdAt"},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by language code (e.g. en, de, es)","title":"Language"},"description":"Filter by language code (e.g. en, de, es)"},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by reaction type (chat or create)","title":"Type"},"description":"Filter by reaction type (chat or create)"},{"name":"basedOn","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/BasedOn"},{"type":"null"}],"description":"Filter by source: 'staticGroup' or 'targetAudience'. If omitted, returns both.","title":"Basedon"},"description":"Filter by source: 'staticGroup' or 'targetAudience'. If omitted, returns both."},{"name":"x-gateway-token","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Gateway-Token"}},{"name":"x-local-workspaceid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspaceid"}},{"name":"x-local-customerid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Customerid"}},{"name":"x-local-userid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Userid"}},{"name":"x-local-roles","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Roles"}},{"name":"x-local-workspacerole","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspacerole"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReactionPage"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/v1/workspaces/{workspace_id}/twins/{twin_id}":{"get":{"tags":["Twins"],"summary":"Get Twin","operationId":"get_twin_v1_workspaces__workspace_id__twins__twin_id__get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"twin_id","in":"path","required":true,"schema":{"type":"string","title":"Twin Id"}},{"name":"x-gateway-token","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Gateway-Token"}},{"name":"x-local-workspaceid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspaceid"}},{"name":"x-local-customerid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Customerid"}},{"name":"x-local-userid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Userid"}},{"name":"x-local-roles","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Roles"}},{"name":"x-local-workspacerole","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspacerole"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwinResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/v1/workspaces/{workspace_id}/twins":{"get":{"tags":["Twins"],"summary":"List Twins","operationId":"list_twins_v1_workspaces__workspace_id__twins_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based)","default":1,"title":"Page"},"description":"Page number (1-based)"},{"name":"size","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":0,"description":"Number of elements per page","default":20,"title":"Size"},"description":"Number of elements per page"},{"name":"sort","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SortField","description":"Sort field: 'name' or 'createdAt'","default":"createdAt"},"description":"Sort field: 'name' or 'createdAt'"},{"name":"order","in":"query","required":false,"schema":{"$ref":"#/components/schemas/modules__twin__request_models__SortOrder","description":"Sort order","default":"desc"},"description":"Sort order"},{"name":"targetAudienceId","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by target audience","title":"Targetaudienceid"},"description":"Filter by target audience"},{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by name prefix (case-insensitive)","title":"Name"},"description":"Filter by name prefix (case-insensitive)"},{"name":"x-gateway-token","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Gateway-Token"}},{"name":"x-local-workspaceid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspaceid"}},{"name":"x-local-customerid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Customerid"}},{"name":"x-local-userid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Userid"}},{"name":"x-local-roles","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Roles"}},{"name":"x-local-workspacerole","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspacerole"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwinPageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/v1/workspaces/{workspace_id}/static-groups/{group_key}/twins":{"get":{"tags":["Twins"],"summary":"List Static Group Twins","operationId":"list_static_group_twins_v1_workspaces__workspace_id__static_groups__group_key__twins_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"group_key","in":"path","required":true,"schema":{"type":"string","title":"Group Key"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based)","default":1,"title":"Page"},"description":"Page number (1-based)"},{"name":"size","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":0,"description":"Number of elements per page","default":20,"title":"Size"},"description":"Number of elements per page"},{"name":"order","in":"query","required":false,"schema":{"$ref":"#/components/schemas/modules__twin__request_models__SortOrder","description":"Sort order by name","default":"asc"},"description":"Sort order by name"},{"name":"twinIds","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated twin IDs to filter for","title":"Twinids"},"description":"Comma-separated twin IDs to filter for"},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"enum":["en","de"],"type":"string"},{"type":"null"}],"description":"Filter by language","title":"Language"},"description":"Filter by language"},{"name":"x-gateway-token","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Gateway-Token"}},{"name":"x-local-workspaceid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspaceid"}},{"name":"x-local-customerid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Customerid"}},{"name":"x-local-userid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Userid"}},{"name":"x-local-roles","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Roles"}},{"name":"x-local-workspacerole","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspacerole"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwinPageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/v1/workspaces/{workspace_id}/twins/{twin_id}/chat-completions":{"post":{"tags":["Chat"],"summary":"Chat With Twin","operationId":"chat_with_twin_v1_workspaces__workspace_id__twins__twin_id__chat_completions_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"twin_id","in":"path","required":true,"schema":{"type":"string","title":"Twin Id"}},{"name":"x-gateway-token","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Gateway-Token"}},{"name":"x-local-workspaceid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspaceid"}},{"name":"x-local-customerid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Customerid"}},{"name":"x-local-userid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Userid"}},{"name":"x-local-roles","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Roles"}},{"name":"x-local-workspacerole","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspacerole"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwinCompletionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/v1/workspaces/{workspace_id}/twin-group-chat-opinions":{"post":{"tags":["Chat"],"summary":"Get Twin Group Opinions","operationId":"get_twin_group_opinions_v1_workspaces__workspace_id__twin_group_chat_opinions_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"x-gateway-token","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Gateway-Token"}},{"name":"x-local-workspaceid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspaceid"}},{"name":"x-local-customerid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Customerid"}},{"name":"x-local-userid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Userid"}},{"name":"x-local-roles","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Roles"}},{"name":"x-local-workspacerole","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspacerole"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwinGroupOpinionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwinGroupCompletionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/v1/workspaces/{workspace_id}/twin-group-chat-completions":{"post":{"tags":["Chat"],"summary":"Chat With Twin Group","operationId":"chat_with_twin_group_v1_workspaces__workspace_id__twin_group_chat_completions_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"x-gateway-token","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Gateway-Token"}},{"name":"x-local-workspaceid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspaceid"}},{"name":"x-local-customerid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Customerid"}},{"name":"x-local-userid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Userid"}},{"name":"x-local-roles","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Roles"}},{"name":"x-local-workspacerole","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspacerole"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwinGroupCompletionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwinGroupCompletionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/v1/workspaces/{workspace_id}/reactions/{reaction_id}/sources":{"get":{"tags":["Sources"],"summary":"Get Reaction Sources","description":"Get article sources for a reaction.\n\nReturns the full article content including RSS feed data and parsed content.\n\nRequires authentication.","operationId":"get_reaction_sources_v1_workspaces__workspace_id__reactions__reaction_id__sources_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"reaction_id","in":"path","required":true,"schema":{"type":"string","description":"The reaction ID","title":"Reaction Id"},"description":"The reaction ID"},{"name":"x-gateway-token","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Gateway-Token"}},{"name":"x-local-workspaceid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspaceid"}},{"name":"x-local-customerid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Customerid"}},{"name":"x-local-userid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Userid"}},{"name":"x-local-roles","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Roles"}},{"name":"x-local-workspacerole","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspacerole"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NewsSourceResponse"},"title":"Response Get Reaction Sources V1 Workspaces  Workspace Id  Reactions  Reaction Id  Sources Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/v1/workspaces/{workspace_id}/target-audiences/{target_audience_id}/twin-creation-jobs/{job_id}":{"get":{"tags":["Twin Creation Jobs"],"summary":"Get Twin Creation Job","operationId":"get_twin_creation_job_v1_workspaces__workspace_id__target_audiences__target_audience_id__twin_creation_jobs__job_id__get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"target_audience_id","in":"path","required":true,"schema":{"type":"string","title":"Target Audience Id"}},{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"x-gateway-token","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Gateway-Token"}},{"name":"x-local-workspaceid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspaceid"}},{"name":"x-local-customerid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Customerid"}},{"name":"x-local-userid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Userid"}},{"name":"x-local-roles","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Roles"}},{"name":"x-local-workspacerole","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspacerole"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwinCreationJob"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/v1/workspaces/{workspace_id}/target-audiences/{target_audience_id}/twin-creation-jobs":{"get":{"tags":["Twin Creation Jobs"],"summary":"List Twin Creation Jobs","operationId":"list_twin_creation_jobs_v1_workspaces__workspace_id__target_audiences__target_audience_id__twin_creation_jobs_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"target_audience_id","in":"path","required":true,"schema":{"type":"string","title":"Target Audience Id"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based)","default":1,"title":"Page"},"description":"Page number (1-based)"},{"name":"size","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":0,"description":"Number of elements per page","default":20,"title":"Size"},"description":"Number of elements per page"},{"name":"order","in":"query","required":false,"schema":{"$ref":"#/components/schemas/modules__twin__request_models__SortOrder","description":"Sort order","default":"desc"},"description":"Sort order"},{"name":"x-gateway-token","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Gateway-Token"}},{"name":"x-local-workspaceid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspaceid"}},{"name":"x-local-customerid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Customerid"}},{"name":"x-local-userid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Userid"}},{"name":"x-local-roles","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Roles"}},{"name":"x-local-workspacerole","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspacerole"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwinCreationJobPage"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]},"post":{"tags":["Twin Creation Jobs"],"summary":"Create Twin Creation Job","operationId":"create_twin_creation_job_v1_workspaces__workspace_id__target_audiences__target_audience_id__twin_creation_jobs_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"target_audience_id","in":"path","required":true,"schema":{"type":"string","title":"Target Audience Id"}},{"name":"x-gateway-token","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Gateway-Token"}},{"name":"x-local-workspaceid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspaceid"}},{"name":"x-local-customerid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Customerid"}},{"name":"x-local-userid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Userid"}},{"name":"x-local-roles","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Roles"}},{"name":"x-local-workspacerole","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspacerole"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTwinCreationJobRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwinCreationJob"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/v1/workspaces/{workspace_id}/audience-twin-metrics":{"get":{"tags":["Audience Twin Metrics"],"summary":"Get Audience Twin Metrics","operationId":"get_audience_twin_metrics_v1_workspaces__workspace_id__audience_twin_metrics_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based)","default":1,"title":"Page"},"description":"Page number (1-based)"},{"name":"size","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":0,"description":"Number of elements per page","default":20,"title":"Size"},"description":"Number of elements per page"},{"name":"targetAudienceIds","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter by target audience IDs","title":"Targetaudienceids"},"description":"Filter by target audience IDs"},{"name":"x-gateway-token","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Gateway-Token"}},{"name":"x-local-workspaceid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspaceid"}},{"name":"x-local-customerid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Customerid"}},{"name":"x-local-userid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Userid"}},{"name":"x-local-roles","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Roles"}},{"name":"x-local-workspacerole","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspacerole"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceTwinMetricsPage"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/health":{"get":{"summary":"Health Check","description":"Health check endpoint.\n\nReturns the service health status, name, version, and environment.","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}},"security":[{"BearerAuth":[]}]}},"/status":{"get":{"summary":"Status Check","description":"Status check endpoint with database connection testing.\n\nRequires admin role. Returns counts of permissions from MySQL\nand surveys from PostgreSQL to verify database connectivity.","operationId":"status_check_status_get","parameters":[{"name":"x-gateway-token","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Gateway-Token"}},{"name":"x-local-workspaceid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspaceid"}},{"name":"x-local-customerid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Customerid"}},{"name":"x-local-userid","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Userid"}},{"name":"x-local-roles","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Roles"}},{"name":"x-local-workspacerole","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Local-Workspacerole"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}}},"components":{"schemas":{"AudienceTwinMetrics":{"properties":{"targetAudienceId":{"type":"string","title":"Targetaudienceid"},"numberOfTwins":{"type":"integer","title":"Numberoftwins"}},"type":"object","required":["targetAudienceId","numberOfTwins"],"title":"AudienceTwinMetrics"},"AudienceTwinMetricsPage":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AudienceTwinMetrics"},"type":"array","title":"Data"},"page":{"$ref":"#/components/schemas/modules__twin__request_models__Page"}},"type":"object","required":["data","page"],"title":"AudienceTwinMetricsPage"},"BasedOn":{"type":"string","enum":["staticGroup","targetAudience"],"title":"BasedOn"},"ChatMessage":{"properties":{"role":{"type":"string","enum":["user","assistant"],"title":"Role","description":"Role: 'user' or 'assistant'"},"content":{"type":"string","title":"Content","description":"Message content"}},"type":"object","required":["role","content"],"title":"ChatMessage","description":"Chat message in OpenAI format.","examples":[{"content":"What do you think about remote work?","role":"user"}]},"CreateTwinCreationJobRequest":{"properties":{"numberOfTwinsToCreate":{"type":"integer","exclusiveMinimum":0.0,"title":"Numberoftwinstocreate","description":"Number of twins to create"}},"type":"object","required":["numberOfTwinsToCreate"],"title":"CreateTwinCreationJobRequest","description":"Request body for creating a twin creation job."},"EmbeddedTwin":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"age":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Age"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"jobTitle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jobtitle"},"staticGroupKey":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Staticgroupkey"},"_links":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"object"},{"type":"null"}],"title":"Links"}},"type":"object","required":["id","name"],"title":"EmbeddedTwin"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Service health status","example":"healthy"},"service":{"type":"string","title":"Service","description":"Service name","example":"digital-twin-service"},"version":{"type":"string","title":"Version","description":"Service version","example":"1.0.0"},"environment":{"type":"string","title":"Environment","description":"Deployment environment","example":"local"}},"type":"object","required":["status","service","version","environment"],"title":"HealthResponse","description":"Health check response model."},"JsonSchema":{"properties":{"name":{"type":"string","maxLength":100,"minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$","title":"Name","description":"Schema name (must be valid identifier)"},"strict":{"type":"boolean","title":"Strict","description":"Whether to enforce strict schema validation","default":true},"schema":{"additionalProperties":true,"type":"object","title":"Schema","description":"JSON schema object (must not be empty)"}},"type":"object","required":["name","schema"],"title":"JsonSchema","description":"JSON schema definition for structured outputs.","examples":[{"name":"enthusiasm_rating","schema":{"additionalProperties":false,"properties":{"rating":{"maximum":10,"minimum":1,"type":"number"},"explanation":{"type":"string"}},"required":["rating","explanation"],"type":"object"},"strict":true}]},"NewsSourceResponse":{"properties":{"accessedAt":{"type":"string","format":"date-time","title":"Accessedat","description":"Timestamp when article was parsed","example":"2026-02-13T10:30:00Z"},"url":{"type":"string","title":"Url","description":"Article URL","example":"https://example.com/article"},"type":{"type":"string","title":"Type","description":"Source type (always 'news')","default":"news","example":"news"},"content":{"additionalProperties":true,"type":"object","title":"Content","description":"Article data with 'rss' and 'parsed' keys"}},"type":"object","required":["accessedAt","url","content"],"title":"NewsSourceResponse","description":"API response model for news sources."},"ReactionEmbedded":{"properties":{"twin":{"anyOf":[{"$ref":"#/components/schemas/EmbeddedTwin"},{"type":"null"}]}},"type":"object","title":"ReactionEmbedded"},"ReactionPage":{"properties":{"data":{"anyOf":[{"items":{"$ref":"#/components/schemas/ReactionResponse"},"type":"array"},{"type":"null"}],"title":"Data","description":"List of reactions for this page"},"page":{"$ref":"#/components/schemas/modules__reaction__router__Page"}},"type":"object","required":["data","page"],"title":"ReactionPage"},"ReactionResponse":{"properties":{"id":{"type":"string","title":"Id"},"createdAt":{"type":"string","title":"Createdat"},"updatedAt":{"type":"string","title":"Updatedat"},"leadTwinId":{"type":"string","title":"Leadtwinid"},"twinIds":{"items":{"type":"string"},"type":"array","title":"Twinids"},"staticGroupKey":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Staticgroupkey"},"targetAudienceId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Targetaudienceid"},"sourceType":{"type":"string","title":"Sourcetype"},"sourceId":{"type":"string","title":"Sourceid"},"quote":{"type":"string","title":"Quote"},"suggestedAction":{"type":"string","title":"Suggestedaction"},"actionLabel":{"type":"string","title":"Actionlabel","default":""},"actionPrompt":{"type":"string","title":"Actionprompt","default":""},"language":{"type":"string","title":"Language","default":"en"},"type":{"type":"string","title":"Type","default":"chat"},"_embedded":{"anyOf":[{"$ref":"#/components/schemas/ReactionEmbedded"},{"type":"null"}]}},"type":"object","required":["id","createdAt","updatedAt","leadTwinId","sourceType","sourceId","quote","suggestedAction"],"title":"ReactionResponse"},"ResponseFormat":{"properties":{"type":{"type":"string","const":"json_schema","title":"Type","description":"Format type (must be 'json_schema')"},"json_schema":{"$ref":"#/components/schemas/JsonSchema","description":"JSON schema definition"}},"type":"object","required":["type","json_schema"],"title":"ResponseFormat","description":"Response format specification for structured outputs.","examples":[{"json_schema":{"name":"enthusiasm_rating","schema":{"additionalProperties":false,"properties":{"rating":{"maximum":10,"minimum":1,"type":"number"},"explanation":{"type":"string"}},"required":["rating","explanation"],"type":"object"},"strict":true},"type":"json_schema"}]},"SortField":{"type":"string","enum":["name","createdAt"],"title":"SortField","description":"Sort field enum for twins list."},"StaticGroup":{"properties":{"key":{"type":"string","title":"Key","description":"Unique identifier for the group","example":"gen_z"},"label":{"type":"string","title":"Label","description":"Display name for the group","example":"Gen Z"},"description":{"type":"string","title":"Description","description":"Detailed description of the group","example":"Generation Z, born between 1997 and 2012"},"language":{"anyOf":[{"type":"string","enum":["en","de"]},{"type":"null"}],"title":"Language","description":"Language code: 'en' or 'de'. None if group is language-agnostic.","example":"en"}},"type":"object","required":["key","label","description"],"title":"StaticGroup","description":"Represents a static demographic group."},"StatusResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Service status","example":"healthy"},"mysql":{"type":"boolean","title":"Mysql","description":"MySQL database connectivity"},"postgres":{"type":"boolean","title":"Postgres","description":"PostgreSQL database connectivity"}},"type":"object","required":["status","mysql","postgres"],"title":"StatusResponse","description":"Status check response model with database connectivity."},"TwinCompletionRequest":{"properties":{"messages":{"items":{"$ref":"#/components/schemas/ChatMessage"},"type":"array","minItems":1,"title":"Messages","description":"Conversation history (at least one message required, last message must be from user)"},"responseFormat":{"anyOf":[{"$ref":"#/components/schemas/ResponseFormat"},{"type":"null"}],"description":"Structured output format using JSON schema. If null, uses default schema with 'answer' and 'reason' fields."},"temperature":{"anyOf":[{"type":"number","maximum":2.0,"minimum":0.0},{"type":"null"}],"title":"Temperature","description":"Sampling temperature for response generation","default":0.7},"useWebSearch":{"anyOf":[{"type":"string","enum":["never","auto","always"]},{"type":"null"}],"title":"Usewebsearch","description":"Web search mode: 'never', 'auto', or 'always'","default":"auto"},"useVerbalizedSampling":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Useverbalizedsampling","description":"Generate 5 probability-weighted response options (tau=0.10). Mutually exclusive with custom responseFormat.","default":true}},"type":"object","required":["messages"],"title":"TwinCompletionRequest","description":"Request body for twin chat completions.","examples":[{"messages":[{"content":"What are your thoughts on artificial intelligence?","role":"user"},{"content":"I find AI fascinating and believe it has tremendous potential to transform society.","role":"assistant"},{"content":"Rate your enthusiasm for AI on a scale of 1-10","role":"user"}],"responseFormat":{"json_schema":{"name":"enthusiasm_rating","schema":{"additionalProperties":false,"properties":{"rating":{"maximum":10,"minimum":1,"type":"number"},"explanation":{"type":"string"}},"required":["rating","explanation"],"type":"object"},"strict":true},"type":"json_schema"},"temperature":0.7,"useVerbalizedSampling":false,"useWebSearch":"auto"}]},"TwinCreationJob":{"properties":{"id":{"type":"string","title":"Id","description":"Unique identifier","example":"550e8400-e29b-41d4-a716-446655440000"},"createdAt":{"type":"string","format":"date-time","title":"Createdat","description":"Timestamp when the record was created","example":"2024-01-15T10:30:00Z"},"updatedAt":{"type":"string","format":"date-time","title":"Updatedat","description":"Timestamp when the record was last updated","example":"2024-01-15T10:30:00Z"},"createdByUserId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Createdbyuserid","description":"ID of the user who created this record","example":"12345"},"targetAudienceId":{"type":"string","title":"Targetaudienceid","description":"Target audience ID this job creates twins for"},"createdTwinIds":{"items":{"type":"string"},"type":"array","title":"Createdtwinids","description":"IDs of twins created by this job"},"finishedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Finishedat","description":"When the job successfully finished processing"},"retries":{"type":"integer","title":"Retries","description":"Number of processing attempts. The job is retried up to 10 times","default":0},"numberOfTwinsToCreate":{"type":"integer","title":"Numberoftwinstocreate","description":"How many twins this job should create"},"successful":{"type":"boolean","title":"Successful","description":"True if the job completed without errors","readOnly":true}},"type":"object","required":["targetAudienceId","numberOfTwinsToCreate","successful"],"title":"TwinCreationJob","description":"Twin creation job entity."},"TwinCreationJobPage":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TwinCreationJob"},"type":"array","title":"Data"},"page":{"$ref":"#/components/schemas/modules__twin__request_models__Page"}},"type":"object","required":["data","page"],"title":"TwinCreationJobPage","description":"Paginated list of twin creation jobs."},"TwinGroupCompletionRequest":{"properties":{"twinIds":{"items":{"type":"string"},"type":"array","maxItems":20,"minItems":1,"title":"Twinids","description":"List of twin IDs to query (max 20)"},"messages":{"items":{"$ref":"#/components/schemas/ChatMessage"},"type":"array","minItems":1,"title":"Messages","description":"Conversation history (at least one message required, last message must be from user)"},"responseFormat":{"anyOf":[{"$ref":"#/components/schemas/ResponseFormat"},{"type":"null"}],"description":"Structured output format for individual twin responses. If null, uses default schema with 'answer' and 'reason' fields."},"temperature":{"anyOf":[{"type":"number","maximum":2.0,"minimum":0.0},{"type":"null"}],"title":"Temperature","description":"Sampling temperature for response generation","default":0.7},"runRar":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Runrar","description":"Enable Rephrase and Respond for question robustness","default":true},"useWebSearch":{"anyOf":[{"type":"string","enum":["never","auto","always"]},{"type":"null"}],"title":"Usewebsearch","description":"Web search mode: 'never', 'auto', or 'always'","default":"auto"},"useVerbalizedSampling":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Useverbalizedsampling","description":"Generate 5 probability-weighted response options per twin. Mutually exclusive with custom responseFormat.","default":true}},"type":"object","required":["twinIds","messages"],"title":"TwinGroupCompletionRequest","description":"Request body for twin group chat completions.","examples":[{"messages":[{"content":"What do you think about remote work?","role":"user"},{"content":"{\"summary\": \"Mixed views on remote work.\", \"twinResponses\": {\"twin-id-1\": {\"answer\": \"I love it!\", \"reason\": \"More flexible\"}, \"twin-id-2\": {\"answer\": \"It's challenging\", \"reason\": \"Miss collaboration\"}}}","role":"assistant"},{"content":"How would you improve it?","role":"user"}],"runRar":true,"temperature":0.7,"twinIds":["twin-id-1","twin-id-2"],"useVerbalizedSampling":true,"useWebSearch":"auto"}]},"TwinGroupCompletionResponse":{"properties":{"summary":{"type":"string","title":"Summary","description":"LLM-generated summary of all twin responses"},"twinResponses":{"additionalProperties":true,"type":"object","title":"Twinresponses","description":"Dictionary mapping twin IDs to their responses"}},"type":"object","required":["summary","twinResponses"],"title":"TwinGroupCompletionResponse","description":"Response body for twin group chat completions."},"TwinGroupOpinionRequest":{"properties":{"twinIds":{"items":{"type":"string"},"type":"array","maxItems":20,"minItems":1,"title":"Twinids","description":"List of twin IDs to query (max 20)"},"question":{"type":"string","maxLength":10000,"minLength":1,"title":"Question","description":"Question to ask all twins."},"responseFormat":{"anyOf":[{"$ref":"#/components/schemas/ResponseFormat"},{"type":"null"}],"description":"Structured output format for individual twin responses. If null, uses default schema with 'answer' and 'reason' fields."}},"type":"object","required":["twinIds","question"],"title":"TwinGroupOpinionRequest","description":"Request body for twin group opinions (simplified endpoint).","examples":[{"question":"Rate your enthusiasm for remote work on a scale of 1-10","responseFormat":{"json_schema":{"name":"enthusiasm_rating","schema":{"additionalProperties":false,"properties":{"rating":{"maximum":10,"minimum":1,"type":"number"},"explanation":{"type":"string"}},"required":["rating","explanation"],"type":"object"},"strict":true},"type":"json_schema"},"twinIds":["twin-id-1","twin-id-2"]}]},"TwinPageResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TwinResponse"},"type":"array","title":"Data","description":"List of twins for this page"},"page":{"$ref":"#/components/schemas/modules__twin__request_models__Page"}},"type":"object","required":["data","page"],"title":"TwinPageResponse","description":"Paginated twin response with TwinResponse objects."},"TwinResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Unique identifier","example":"550e8400-e29b-41d4-a716-446655440000"},"createdAt":{"type":"string","format":"date-time","title":"Createdat","description":"Timestamp when the record was created","example":"2024-01-15T10:30:00Z"},"updatedAt":{"type":"string","format":"date-time","title":"Updatedat","description":"Timestamp when the record was last updated","example":"2024-01-15T10:30:00Z"},"createdByUserId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Createdbyuserid","description":"ID of the user who created this record","example":"12345"},"targetAudienceId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Targetaudienceid","description":"Target audience ID (either this or staticGroupKey must be set)","example":"aud_12345"},"staticGroupKey":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Staticgroupkey","description":"Key of the associated static group (either this or targetAudienceId must be set)","example":"millennials"},"subjectId":{"type":"string","title":"Subjectid","description":"ID of the subject this twin is based on","example":"550e8400-e29b-41d4-a716-446655440000"},"name":{"type":"string","title":"Name","description":"Full name of the digital twin","example":"Jens Bauer"},"language":{"type":"string","enum":["en","de"],"title":"Language","description":"Language code: 'en' or 'de'","example":"en"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Descriptive title for the digital twin","example":"Tech-Savvy Millennial"},"age":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Age","description":"Age of the digital twin","example":28},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender","description":"Gender of the digital twin","example":"Male"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location","description":"Location of the digital twin","example":"Berlin, Germany"},"jobTitle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jobtitle","description":"Job title of the digital twin","example":"Software Engineer"},"selfDescription":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selfdescription","description":"Self-description of the digital twin from survey responses","example":"I'm a tech enthusiast who loves innovation and problem-solving."},"_links":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"object"},{"type":"null"}],"title":"Links","description":"HATEOAS links (e.g., avatarUrl)"}},"type":"object","required":["subjectId","name","language"],"title":"TwinResponse","description":"Twin response with HATEOAS links.","exclude":["modified_survey_result","modified_survey_result_values"]},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"modules__reaction__router__Page":{"properties":{"size":{"type":"integer","title":"Size","description":"Number of elements per page"},"totalElements":{"type":"integer","title":"Totalelements","description":"Total number of matching elements"},"totalPages":{"type":"integer","title":"Totalpages","description":"Total number of pages"},"currentPage":{"type":"integer","title":"Currentpage","description":"Current page number (1-based)"}},"type":"object","required":["size","totalElements","totalPages","currentPage"],"title":"Page"},"modules__reaction__router__SortOrder":{"type":"string","enum":["asc","desc"],"title":"SortOrder"},"modules__twin__request_models__Page":{"properties":{"size":{"type":"integer","title":"Size","description":"Number of elements per page"},"totalElements":{"type":"integer","title":"Totalelements","description":"Total number of matching elements"},"totalPages":{"type":"integer","title":"Totalpages","description":"Total number of pages"},"currentPage":{"type":"integer","title":"Currentpage","description":"Current page number (1-based)"}},"type":"object","required":["size","totalElements","totalPages","currentPage"],"title":"Page","description":"Pagination metadata."},"modules__twin__request_models__SortOrder":{"type":"string","enum":["asc","desc"],"title":"SortOrder","description":"Sort order enum."}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Enter your JWT token"}}}}