FastGPTFastGPT

Initialize Chat Session

Initialize an app or skill debug chat session and retrieve welcome text, variables, module settings, and conversation state.

Endpoint Overview

  • Method : GET
  • Path : /api/core/chat/init
  • Module : Chat / Chat History
  • Authentication : Authorization: Bearer <apiKey>—Supports App API Key ( appId optional) and Personal API Key ( appId required); also supports authProxy team member proxy (see API Getting Started )
  • Interactive Try-It-Out : Open in Scalar API Explorer (self-hosted instances: replace the origin with <instance>/apidoc/systemopenapi#tag/%E4%BC%9A%E8%AF%9D%E7%AE%A1%E7%90%86/GET/core/chat/init )

Description & Notes

Initializes an application chat session or a Skill Edit debug session, returning chat configuration, variables, and existing conversation state.

Pass either appId (app chat) or skillId (skill debug) together with chatId in Query parameters ( skillId takes precedence if both are provided).

For builder assistant sessions, pass appId with sourceType ( chatAgentHelper or workflowBuilder ); omit sourceType for regular app chats.

Share-link sessions use GET /api/core/chat/outLink/init with JSON-serialized outLinkAuthData . Starting or resuming a skill runtime sandbox uses POST /api/core/ai/skill/runtime/init .

Request Parameters

Query Parameters

Shared Parameters Across Branches

FieldTypeRequiredDefaultConstraints & Description
chatIdstringYes-Chat ID. minLength: 1; maxLength: 1024
loadCustomFeedbacksbooleanNo-Whether to load custom feedback items

Mutually Exclusive Branches ( anyOf )

  • App Chat

Identify the conversation via appId . When both API Key and login session are supported, Authorization takes precedence over token/Cookie.

FieldTypeRequiredDefaultConstraints & Description
appIdstringYes-Application ID authenticated with the request header credentials allowed by this endpoint. pattern: ^[0-9a-fA-F]{24}$
sourceTypestring (enum)No-Session resource type associated with appId . Defaults to app ; pass the matching sourceType for assistant builder sessions. Allowed values: app , chatAgentHelper , workflowBuilder

Default Identity : Omit customUid and authProxy to execute using the team member identity associated with the credential.

Custom end user ( customUid ): Tag end users from your own system via customUid without changing the authenticating member or permissions. Passed as workflow userId and used to scope chat management.

FieldTypeRequiredDefaultConstraints & Description
customUidstringYes-Supported only for standard app API Key calls. Exact match against the external user ID ( outLinkUid , not tmbId ). Omit to keep full scope or pass to restrict reads, updates, and deletions (max 1024 chars, cannot be empty or null , does not change member identity). minLength: 1; maxLength: 1024

Proxy Team Member ( authProxy ): Act on behalf of another member in the same team via authProxy . Available only on personal API keys with authProxy enabled; mutually exclusive with customUid .

FieldTypeRequiredDefaultConstraints & Description
authProxystringYes-JSON-serialized proxy identity, e.g. {"tmbId":"member-id"} or {"username":"alice"}
  • Skill Debug Session

Identify the debug session via skillId (takes precedence over appId and ignores sourceType ), authenticated with allowed request header credentials.

FieldTypeRequiredDefaultConstraints & Description
skillIdstringYes-Skill Edit debug ID authenticated with allowed request header credentials. pattern: ^[0-9a-fA-F]{24}$
  • App API Key (no appId required)

When authorizing with an app-bound App API Key, omit appId and sourceType ; the server resolves the bound app with sourceType fixed to app . Personal keys and login sessions cannot omit appId , and an explicit appId does not override an App API Key binding.

Default Identity : Omit customUid and authProxy to execute using the team member identity associated with the credential.

Custom end user ( customUid ): Tag end users from your own system via customUid without changing the authenticating member or permissions. Passed as workflow userId and used to scope chat management.

FieldTypeRequiredDefaultConstraints & Description
customUidstringYes-Supported only for standard app API Key calls. Exact match against the external user ID ( outLinkUid , not tmbId ). Omit to keep full scope or pass to restrict reads, updates, and deletions (max 1024 chars, cannot be empty or null , does not change member identity). minLength: 1; maxLength: 1024

Request Examples

Replace YOUR_API_KEY and placeholder IDs before running. Self-hosted users should replace the base URL with <instance>/api .

cURL Example

curl --fail-with-body -X GET "https://cloud.fastgpt.io/api/core/chat/init?appId=68ad85a7463006c963799a05&chatId=1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Schema & Examples

Successful /api/* calls return the standard FastGPT envelope { "code": 200, "statusText": "", "message": "", "data": ... } , where data matches the 200 schema below (when a payload schema is declared; otherwise refer to the status description for runtime data semantics).

HTTP 200

Successfully returned chat initialization data

Content-Type : application/json

FieldTypeRequiredDefaultConstraints & Description
chatIdstringNo-Chat ID. maxLength: 1024
userAvatarstringNo-User avatar URL
titlestringYes-Chat title
variablesobjectNo-Global variable values
chatGenerateStatusnumber (enum)No-Live generation status from Redis lease: 0 ( generating ), 1 ( done / idle). Allowed values: 0 , 1
hasBeenReadbooleanNo-Whether the conversation has been read
appobjectYes-Application configuration
app.chatConfigobjectNo-Chat configuration
app.chatConfig.welcomeTextstringNo-Welcome message displayed when starting a new conversation
app.chatConfig.welcomeConfigobjectNo-Opening prompt configuration
app.chatConfig.welcomeConfig.welcomeTextstringNo-Welcome message displayed when starting a new conversation
app.chatConfig.welcomeConfig.welcomeQuestionsstring[]No-Suggested starter questions shown below the welcome text
app.chatConfig.variablesobject[]No-List of variables users fill in before starting a conversation
app.chatConfig.variables[].maxFilesintegerNo-Maximum number of files allowed for this variable. min: 0; max: 9007199254740991
app.chatConfig.variables[].canSelectFilebooleanNo-Whether regular document files are allowed for this variable
app.chatConfig.variables[].customPdfParsebooleanNo-Whether custom PDF parsing is enabled
app.chatConfig.variables[].canSelectImgbooleanNo-Whether images are allowed for this variable
app.chatConfig.variables[].canSelectVideobooleanNo-Whether videos are allowed for this variable
app.chatConfig.variables[].canSelectAudiobooleanNo-Whether audio files are allowed for this variable
app.chatConfig.variables[].canSelectCustomFileExtensionbooleanNo-Whether custom file extensions are allowed for this variable
app.chatConfig.variables[].customFileExtensionListstring[]No-List of allowed custom file extensions for this variable
app.chatConfig.variables[].keystringYes-Variable key used in prompts and workflow references
app.chatConfig.variables[].labelstringYes-Variable display label
app.chatConfig.variables[].valueTypestring (enum)No-Variable value data type. Allowed values: string , number , boolean , object , arrayString , arrayNumber , arrayBoolean , arrayObject , arrayAny , any , chatHistory , datasetQuote , dynamic , selectDataset , selectApp
app.chatConfig.variables[].requiredbooleanNo-Whether this variable is required
app.chatConfig.variables[].defaultValueobject | array | string | number | boolean | nullNo-Default value for the variable
app.chatConfig.variables[].referencePlaceholderstringNo-Placeholder text displayed when referencing the variable
app.chatConfig.variables[].isRichTextbooleanNo-Whether rich-text input is enabled
app.chatConfig.variables[].placeholderstringNo-Input field placeholder text
app.chatConfig.variables[].maxLengthintegerNo-Maximum input character length for text variables. min: 0; max: 9007199254740991
app.chatConfig.variables[].minLengthintegerNo-Minimum input character length for text variables. min: 0; max: 9007199254740991
app.chatConfig.variables[].markListobject[]No-Scale tick marks for numeric slider variables
app.chatConfig.variables[].stepnumberNo-Numeric step increment
app.chatConfig.variables[].maxnumberNo-Maximum numeric value
app.chatConfig.variables[].minnumberNo-Minimum numeric value
app.chatConfig.variables[].precisionnumberNo-Decimal precision for numeric variables
app.chatConfig.variables[].canLocalUploadbooleanNo-Whether local file upload is allowed for this variable
app.chatConfig.variables[].canUrlUploadbooleanNo-Whether importing files by URL is allowed for this variable
app.chatConfig.variables[].timeGranularitystring (enum)No-Granularity of time selection. Allowed values: day , hour , minute , second
app.chatConfig.variables[].timeRangeStartstringNo-Start timestamp of the time range variable
app.chatConfig.variables[].timeRangeEndstringNo-End timestamp of the time range variable
app.chatConfig.variables[].datasetOptionsobject[]No-Selectable datasets for dataset-picker variables
app.chatConfig.variables[].customInputConfigobjectNo-Custom input configuration in the workflow editor
app.chatConfig.variables[].typestring (enum)Yes-Variable input component type. Allowed values: input , textarea , numberInput , select , multipleSelect , timePointSelect , timeRangeSelect , switch , password , file , llmSelect , datasetSelect , custom , internal
app.chatConfig.variables[].descriptionstringYes-Description of the variable purpose
app.chatConfig.variables[].listobject[]No-Options for select-type variables
app.chatConfig.variables[].enumsobject[]No-Deprecated . Deprecated: legacy enum options
app.chatConfig.autoExecuteobjectNo-Auto-execute configuration
app.chatConfig.autoExecute.openbooleanYes-Whether to trigger execution automatically when opening a chat
app.chatConfig.autoExecute.defaultPromptstringYes""Default prompt injected during auto-execution
app.chatConfig.questionGuideobjectNo-Follow-up question suggestion configuration
app.chatConfig.questionGuide.openbooleanYes-Whether follow-up question suggestions are enabled
app.chatConfig.questionGuide.modelIdstringNo-Model ID used to generate follow-up question suggestions
app.chatConfig.questionGuide.modelstringNo-Deprecated . Legacy model identifier for follow-up suggestions
app.chatConfig.questionGuide.customPromptstringNo-Custom prompt appended for follow-up suggestions
app.chatConfig.ttsConfigobjectNo-Text-to-speech (TTS) configuration
app.chatConfig.ttsConfig.typestring (enum)Yes-TTS output mode: disabled, browser TTS, or model TTS. Allowed values: none , web , model
app.chatConfig.ttsConfig.modelIdstringNo-TTS model ID used for speech synthesis
app.chatConfig.ttsConfig.modelstringNo-Deprecated . TTS model name used for speech synthesis
app.chatConfig.ttsConfig.voicestringNo-TTS voice identifier
app.chatConfig.ttsConfig.speednumberNo-TTS playback speed
app.chatConfig.whisperConfigobjectNo-Speech-to-text (STT) input configuration
app.chatConfig.whisperConfig.openbooleanYes-Whether voice input transcription is enabled
app.chatConfig.whisperConfig.autoSendbooleanYesfalseWhether to auto-send after voice transcription completes
app.chatConfig.whisperConfig.autoTTSResponsebooleanYesfalseWhether to auto-play TTS replies after voice input
app.chatConfig.scheduledTriggerConfigobjectNo-Scheduled trigger configuration
app.chatConfig.scheduledTriggerConfig.cronStringstringYes-Cron schedule expression
app.chatConfig.scheduledTriggerConfig.timezonestringYes-Timezone used by the schedule
app.chatConfig.scheduledTriggerConfig.defaultPromptstringYes""Default prompt injected on scheduled runs
app.chatConfig.chatInputGuideobjectNo-Chat input guide configuration
app.chatConfig.chatInputGuide.openbooleanYes-Whether chat input guidance is enabled
app.chatConfig.chatInputGuide.customUrlstringYes-Custom input guide page URL
app.chatConfig.fileSelectConfigobjectNo-Chat file upload configuration
app.chatConfig.fileSelectConfig.maxFilesintegerNo-Maximum files allowed per chat turn. min: 0; max: 9007199254740991
app.chatConfig.fileSelectConfig.canSelectFilebooleanNo-Whether document files can be uploaded in chat
app.chatConfig.fileSelectConfig.customPdfParsebooleanNo-Whether custom PDF parsing is enabled
app.chatConfig.fileSelectConfig.canSelectImgbooleanNo-Whether images can be uploaded in chat
app.chatConfig.fileSelectConfig.canSelectVideobooleanNo-Whether videos can be uploaded in chat
app.chatConfig.fileSelectConfig.canSelectAudiobooleanNo-Whether audio files can be uploaded in chat
app.chatConfig.fileSelectConfig.canSelectCustomFileExtensionbooleanNo-Whether custom file extensions are allowed in chat
app.chatConfig.fileSelectConfig.customFileExtensionListstring[]No-List of allowed custom file extensions in chat
app.chatConfig.entryPointsobject[]No-Feature menu entries shown on the chat page
app.chatConfig.entryPoints[].idstringYes--
app.chatConfig.entryPoints[].namestringYes--
app.chatConfig.entryPoints[].iconstringNo--
app.chatConfig.instructionstringNo-Usage instructions shown to users on the chat page
app.chatModelsstring[]No-Chat model
app.namestringYes-Application name. minLength: 1
app.avatarstringYes-Application avatar URL
app.introstringYes-Application introduction
app.canUsebooleanNo-Whether the resource is available
app.typestring (enum)Yes-Application type. Allowed values: folder , toolFolder , simple , chatAgent , advanced , plugin , toolSet , httpToolSet , hidden , tool , httpPlugin
app.pluginInputsobject[]Yes-Plugin input
app.pluginInputs[].keystringYes-Variable key used in prompts and workflow references
app.pluginInputs[].labelstringYes-Variable display label
app.pluginInputs[].valueTypestring (enum)No-Variable value data type. Allowed values: string , number , boolean , object , arrayString , arrayNumber , arrayBoolean , arrayObject , arrayAny , any , chatHistory , datasetQuote , dynamic , selectDataset , selectApp
app.pluginInputs[].requiredbooleanNo-Whether this variable is required
app.pluginInputs[].defaultValueobject | array | string | number | boolean | nullNo-Default value for the variable
app.pluginInputs[].referencePlaceholderstringNo-Placeholder text displayed when referencing the variable
app.pluginInputs[].isRichTextbooleanNo-Whether rich-text input is enabled
app.pluginInputs[].placeholderstringNo-Input field placeholder text
app.pluginInputs[].maxLengthintegerNo-Maximum input character length for text variables. min: 0; max: 9007199254740991
app.pluginInputs[].minLengthintegerNo-Minimum input character length for text variables. min: 0; max: 9007199254740991
app.pluginInputs[].markListobject[]No-Scale tick marks for numeric slider variables
app.pluginInputs[].markList[].labelstringYes-Tick label
app.pluginInputs[].markList[].valuenumberYes-Tick numeric value
app.pluginInputs[].stepnumberNo-Numeric step increment
app.pluginInputs[].maxnumberNo-Maximum numeric value
app.pluginInputs[].minnumberNo-Minimum numeric value
app.pluginInputs[].precisionnumberNo-Decimal precision for numeric variables
app.pluginInputs[].canSelectFilebooleanNo-Whether regular document files are allowed for this variable
app.pluginInputs[].canSelectImgbooleanNo-Whether images are allowed for this variable
app.pluginInputs[].canSelectVideobooleanNo-Whether videos are allowed for this variable
app.pluginInputs[].canSelectAudiobooleanNo-Whether audio files are allowed for this variable
app.pluginInputs[].canSelectCustomFileExtensionbooleanNo-Whether custom file extensions are allowed for this variable
app.pluginInputs[].customFileExtensionListstring[]No-List of allowed custom file extensions for this variable
app.pluginInputs[].canLocalUploadbooleanNo-Whether local file upload is allowed for this variable
app.pluginInputs[].canUrlUploadbooleanNo-Whether importing files by URL is allowed for this variable
app.pluginInputs[].maxFilesintegerNo-Maximum number of files allowed for this variable. min: 0; max: 9007199254740991
app.pluginInputs[].timeGranularitystring (enum)No-Granularity of time selection. Allowed values: day , hour , minute , second
app.pluginInputs[].timeRangeStartstringNo-Start timestamp of the time range variable
app.pluginInputs[].timeRangeEndstringNo-End timestamp of the time range variable
app.pluginInputs[].datasetOptionsobject[]No-Selectable datasets for dataset-picker variables
app.pluginInputs[].datasetOptions[].datasetIdstringYes-Selectable dataset ID
app.pluginInputs[].datasetOptions[].avatarstringYes-Selectable dataset icon URL
app.pluginInputs[].datasetOptions[].namestringYes-Selectable dataset name
app.pluginInputs[].datasetOptions[].vectorModelobjectYes--
app.pluginInputs[].datasetOptions[].errorstringNo--
app.pluginInputs[].customInputConfigobjectNo-Custom input configuration in the workflow editor
app.pluginInputs[].customInputConfig.selectValueTypeListstring (enum)[]`No-Allowed value types for custom variable input
app.pluginInputs[].customInputConfig.showDefaultValuebooleanNo-Whether to show default value settings in the editor
app.pluginInputs[].customInputConfig.showDescriptionbooleanNo-Whether to show field description settings in the editor
app.pluginInputs[].customInputConfig.hideBottomDividerbooleanNo-Whether to hide the bottom divider in variable editing
app.pluginInputs[].selectedTypestring (enum)No-Active UI render type for multi-type inputs. Allowed values: reference , input , textarea , numberInput , switch , select , multipleSelect , JSONEditor , addInputParam , customVariable , selectApp , selectLLMModel , settingLLMModel , selectDataset , selectDatasetParamsModal , settingDatasetQuotePrompt , hidden , custom , selectSkill , selectTool……
app.pluginInputs[].renderTypeListstring (enum)[]`Yes-Allowed UI render types in the workflow editor
app.pluginInputs[].valueDescstringNo-Human-readable description of the input value
app.pluginInputs[].valueobject | array | string | number | boolean | nullNo-Current Node.js input value
app.pluginInputs[].debugLabelstringNo-Input label shown in debug mode
app.pluginInputs[].descriptionstringNo-Node.js input description
app.pluginInputs[].toolDescriptionstringNo-Semantic description when exposed as a tool parameter
app.pluginInputs[].defaultToAgentGeneratedbooleanNo-Whether the Agent populates this parameter by default when unset
app.pluginInputs[].canAgentGeneratedbooleanNo-Whether Agent auto-generation is allowed for this input
app.pluginInputs[].customJsonSchemaobjectNo-Custom JSON Schema property definition for tool parameters
app.pluginInputs[].enumstringNo-Deprecated: legacy enum configuration
app.pluginInputs[].inputListobject[]No-List of system input definitions
app.pluginInputs[].inputList[].keystringYes-Input key name
app.pluginInputs[].inputList[].labelstringYes-Input display label
app.pluginInputs[].inputList[].descriptionstringNo-Input description
app.pluginInputs[].inputList[].placeholderstringNo-Input placeholder text
app.pluginInputs[].inputList[].requiredbooleanNo-Whether this input is required
app.pluginInputs[].inputList[].inputTypestring (enum)Yes-Input render component type. Allowed values: input , numberInput , secret , switch , select
app.pluginInputs[].inputList[].valueobjectNo-Default value or secret configuration
app.pluginInputs[].inputList[].listobject[]No-Options for select-type system inputs
app.pluginInputs[].canEditbooleanNo-Whether this input can be edited in the editor
app.pluginInputs[].isProbooleanNo-Whether this input requires a commercial edition
app.pluginInputs[].isToolOutputbooleanNo-Whether this input originates from a tool output
app.pluginInputs[].deprecatedbooleanNo-Whether this input is deprecated
app.pluginInputs[].listobject[]No-Options for select-type variables
app.pluginInputs[].list[].labelstringYes-Option display label
app.pluginInputs[].list[].valuestringYes-Option underlying value
app.pluginInputs[].list[].iconstringNo-Option icon
app.pluginInputs[].list[].descriptionstringNo-Option description
app.pluginInputs[].enumsobject[]No-Deprecated . Deprecated: legacy enum options
app.pluginInputs[].enums[].valuestringYes-Enum option value
app.pluginInputs[].enums[].labelstringYes-Enum option display label
app.useAgentSandboxbooleanNo-Whether VM execution is enabled

Mutually Exclusive Branches ( anyOf )

  • Option 1
FieldTypeRequiredDefaultConstraints & Description
appIdstringYes-Application ID; returned only for workflow builder assistant sessions. pattern: ^[0-9a-fA-F]{24}$
skillIdanyNo--
sourceType"workflowBuilder"Yes-Resource type for workflow builder sessions. Fixed: "workflowBuilder"
  • Option 2
FieldTypeRequiredDefaultConstraints & Description
appIdstringYes-Application ID; returned only for chatAgentHelper sessions. pattern: ^[0-9a-fA-F]{24}$
skillIdanyNo--
sourceType"chatAgentHelper"Yes-Resource type for chatAgentHelper sessions. Fixed: "chatAgentHelper"
  • Option 3
FieldTypeRequiredDefaultConstraints & Description
appIdstringYes-Application ID; returned only for standard app chat sessions. pattern: ^[0-9a-fA-F]{24}$
skillIdanyNo--
  • Option 4
FieldTypeRequiredDefaultConstraints & Description
appIdanyNo--
skillIdstringYes-Skill Edit debug ID; returned only for Skill Edit sessions. pattern: ^[0-9a-fA-F]{24}$
Edit on GitHub

Last updated

On this page

Put your business knowledge to work with AI

Import company documents and build accurate, reliable, traceable AI answers.