Update session state
curl --request PATCH \
--url http://localhost:8000/apps/{app_name}/users/{user_id}/sessions/{session_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"stateDelta": {
"language": "zh"
}
}
'import requests
url = "http://localhost:8000/apps/{app_name}/users/{user_id}/sessions/{session_id}"
payload = { "stateDelta": { "language": "zh" } }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({stateDelta: {language: 'zh'}})
};
fetch('http://localhost:8000/apps/{app_name}/users/{user_id}/sessions/{session_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "<string>",
"appName": "<string>",
"userId": "<string>",
"state": {},
"events": [
{
"modelVersion": "<string>",
"content": {
"parts": [
{
"mediaResolution": {
"level": "MEDIA_RESOLUTION_UNSPECIFIED",
"numTokens": 123
},
"codeExecutionResult": {
"outcome": "OUTCOME_UNSPECIFIED",
"output": "<string>",
"id": "<string>"
},
"executableCode": {
"code": "<string>",
"language": "LANGUAGE_UNSPECIFIED",
"id": "<string>"
},
"fileData": {
"displayName": "<string>",
"fileUri": "<string>",
"mimeType": "<string>"
},
"functionCall": {
"id": "<string>",
"args": {},
"name": "<string>",
"partialArgs": [
{
"boolValue": true,
"jsonPath": "<string>",
"nullValue": "NULL_VALUE",
"numberValue": 123,
"stringValue": "<string>",
"willContinue": true
}
],
"willContinue": true
},
"functionResponse": {
"willContinue": true,
"scheduling": "SCHEDULING_UNSPECIFIED",
"parts": [
{
"inlineData": {
"mimeType": "<string>",
"data": "<string>",
"displayName": "<string>"
},
"fileData": {
"fileUri": "<string>",
"mimeType": "<string>",
"displayName": "<string>"
}
}
],
"id": "<string>",
"name": "<string>",
"response": {}
},
"inlineData": {
"data": "<string>",
"displayName": "<string>",
"mimeType": "<string>"
},
"text": "<string>",
"thought": true,
"thoughtSignature": "<string>",
"videoMetadata": {
"endOffset": "<string>",
"fps": 123,
"startOffset": "<string>"
},
"toolCall": {
"id": "<string>",
"toolType": "TOOL_TYPE_UNSPECIFIED",
"args": {}
},
"toolResponse": {
"id": "<string>",
"toolType": "TOOL_TYPE_UNSPECIFIED",
"response": {}
},
"partMetadata": {}
}
],
"role": "<string>"
},
"groundingMetadata": {
"imageSearchQueries": [
"<string>"
],
"groundingChunks": [
{
"image": {
"sourceUri": "<string>",
"imageUri": "<string>",
"title": "<string>",
"domain": "<string>"
},
"maps": {
"placeAnswerSources": {
"reviewSnippet": [
{
"authorAttribution": {
"displayName": "<string>",
"photoUri": "<string>",
"uri": "<string>"
},
"flagContentUri": "<string>",
"googleMapsUri": "<string>",
"relativePublishTimeDescription": "<string>",
"review": "<string>",
"reviewId": "<string>",
"title": "<string>"
}
],
"flagContentUri": "<string>",
"reviewSnippets": [
{
"authorAttribution": {
"displayName": "<string>",
"photoUri": "<string>",
"uri": "<string>"
},
"flagContentUri": "<string>",
"googleMapsUri": "<string>",
"relativePublishTimeDescription": "<string>",
"review": "<string>",
"reviewId": "<string>",
"title": "<string>"
}
]
},
"placeId": "<string>",
"text": "<string>",
"title": "<string>",
"uri": "<string>",
"route": {
"distanceMeters": 123,
"duration": "<string>",
"encodedPolyline": "<string>"
}
},
"retrievedContext": {
"documentName": "<string>",
"ragChunk": {
"pageSpan": {
"firstPage": 123,
"lastPage": 123
},
"text": "<string>",
"chunkId": "<string>",
"fileId": "<string>"
},
"text": "<string>",
"title": "<string>",
"uri": "<string>",
"customMetadata": [
{
"key": "<string>",
"numericValue": 123,
"stringListValue": {
"values": [
"<string>"
]
},
"stringValue": "<string>"
}
],
"fileSearchStore": "<string>",
"pageNumber": 123,
"mediaId": "<string>"
},
"web": {
"domain": "<string>",
"title": "<string>",
"uri": "<string>"
}
}
],
"groundingSupports": [
{
"confidenceScores": [
123
],
"groundingChunkIndices": [
123
],
"segment": {
"startIndex": 123,
"endIndex": 123,
"partIndex": 123,
"text": "<string>"
},
"renderedParts": [
123
]
}
],
"retrievalMetadata": {
"googleSearchDynamicRetrievalScore": 123
},
"searchEntryPoint": {
"renderedContent": "<string>",
"sdkBlob": "<string>"
},
"webSearchQueries": [
"<string>"
],
"googleMapsWidgetContextToken": "<string>",
"retrievalQueries": [
"<string>"
],
"sourceFlaggingUris": [
{
"flagContentUri": "<string>",
"sourceId": "<string>"
}
]
},
"partial": true,
"turnComplete": true,
"turnCompleteReason": "TURN_COMPLETE_REASON_UNSPECIFIED",
"finishReason": "FINISH_REASON_UNSPECIFIED",
"errorCode": "<string>",
"errorMessage": "<string>",
"interrupted": true,
"customMetadata": {},
"usageMetadata": {
"cacheTokensDetails": [
{
"modality": "MODALITY_UNSPECIFIED",
"tokenCount": 123
}
],
"cachedContentTokenCount": 123,
"candidatesTokenCount": 123,
"candidatesTokensDetails": [
{
"modality": "MODALITY_UNSPECIFIED",
"tokenCount": 123
}
],
"promptTokenCount": 123,
"promptTokensDetails": [
{
"modality": "MODALITY_UNSPECIFIED",
"tokenCount": 123
}
],
"thoughtsTokenCount": 123,
"toolUsePromptTokenCount": 123,
"toolUsePromptTokensDetails": [
{
"modality": "MODALITY_UNSPECIFIED",
"tokenCount": 123
}
],
"totalTokenCount": 123,
"trafficType": "TRAFFIC_TYPE_UNSPECIFIED"
},
"liveSessionResumptionUpdate": {
"newHandle": "<string>",
"resumable": true,
"lastConsumedClientMessageIndex": 123
},
"liveSessionId": "<string>",
"goAway": {
"timeLeft": "<string>"
},
"inputTranscription": {
"text": "<string>",
"finished": true,
"languageCode": "<string>"
},
"outputTranscription": {
"text": "<string>",
"finished": true,
"languageCode": "<string>"
},
"avgLogprobs": 123,
"logprobsResult": {
"chosenCandidates": [
{
"logProbability": 123,
"token": "<string>",
"tokenId": 123
}
],
"topCandidates": [
{
"candidates": [
{
"logProbability": 123,
"token": "<string>",
"tokenId": 123
}
]
}
],
"logProbabilitySum": 123
},
"cacheMetadata": {
"fingerprint": "<string>",
"contents_count": 1,
"cache_name": "<string>",
"expire_time": 123,
"invocations_used": 1,
"created_at": 123
},
"citationMetadata": {
"citations": [
{
"endIndex": 123,
"license": "<string>",
"publicationDate": {
"day": 123,
"month": 123,
"year": 123
},
"startIndex": 123,
"title": "<string>",
"uri": "<string>"
}
]
},
"interactionId": "<string>",
"invocationId": "",
"author": "",
"actions": {
"skipSummarization": true,
"stateDelta": {},
"artifactDelta": {},
"transferToAgent": "<string>",
"escalate": true,
"requestedAuthConfigs": {},
"requestedToolConfirmations": {},
"compaction": {
"startTimestamp": 123,
"endTimestamp": 123,
"compactedContent": {
"parts": [
{
"mediaResolution": {
"level": "MEDIA_RESOLUTION_UNSPECIFIED",
"numTokens": 123
},
"codeExecutionResult": {
"outcome": "OUTCOME_UNSPECIFIED",
"output": "<string>",
"id": "<string>"
},
"executableCode": {
"code": "<string>",
"language": "LANGUAGE_UNSPECIFIED",
"id": "<string>"
},
"fileData": {
"displayName": "<string>",
"fileUri": "<string>",
"mimeType": "<string>"
},
"functionCall": {
"id": "<string>",
"args": {},
"name": "<string>",
"partialArgs": [
{
"boolValue": true,
"jsonPath": "<string>",
"nullValue": "NULL_VALUE",
"numberValue": 123,
"stringValue": "<string>",
"willContinue": true
}
],
"willContinue": true
},
"functionResponse": {
"willContinue": true,
"scheduling": "SCHEDULING_UNSPECIFIED",
"parts": [
{
"inlineData": {
"mimeType": "<string>",
"data": "<string>",
"displayName": "<string>"
},
"fileData": {
"fileUri": "<string>",
"mimeType": "<string>",
"displayName": "<string>"
}
}
],
"id": "<string>",
"name": "<string>",
"response": {}
},
"inlineData": {
"data": "<string>",
"displayName": "<string>",
"mimeType": "<string>"
},
"text": "<string>",
"thought": true,
"thoughtSignature": "<string>",
"videoMetadata": {
"endOffset": "<string>",
"fps": 123,
"startOffset": "<string>"
},
"toolCall": {
"id": "<string>",
"toolType": "TOOL_TYPE_UNSPECIFIED",
"args": {}
},
"toolResponse": {
"id": "<string>",
"toolType": "TOOL_TYPE_UNSPECIFIED",
"response": {}
},
"partMetadata": {}
}
],
"role": "<string>"
}
},
"endOfAgent": true,
"agentState": {},
"rewindBeforeInvocationId": "<string>",
"route": true,
"renderUiWidgets": [
{
"id": "<string>",
"provider": "<string>",
"payload": {}
}
],
"setModelResponse": null
},
"output": null,
"nodeInfo": {
"path": "",
"outputFor": [
"<string>"
],
"messageAsOutput": true
},
"longRunningToolIds": [
"<string>"
],
"branch": "<string>",
"isolationScope": "<string>",
"id": "",
"timestamp": 123
}
],
"lastUpdateTime": 0
}{
"detail": "<string>"
}{
"error": "CONTENT_LENGTH_REQUIRED"
}{
"error": "REQUEST_TOO_LARGE"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Sessions
Update session state
Apply stateDelta and save a state-update event without running the agent
PATCH
/
apps
/
{app_name}
/
users
/
{user_id}
/
sessions
/
{session_id}
Update session state
curl --request PATCH \
--url http://localhost:8000/apps/{app_name}/users/{user_id}/sessions/{session_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"stateDelta": {
"language": "zh"
}
}
'import requests
url = "http://localhost:8000/apps/{app_name}/users/{user_id}/sessions/{session_id}"
payload = { "stateDelta": { "language": "zh" } }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({stateDelta: {language: 'zh'}})
};
fetch('http://localhost:8000/apps/{app_name}/users/{user_id}/sessions/{session_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "<string>",
"appName": "<string>",
"userId": "<string>",
"state": {},
"events": [
{
"modelVersion": "<string>",
"content": {
"parts": [
{
"mediaResolution": {
"level": "MEDIA_RESOLUTION_UNSPECIFIED",
"numTokens": 123
},
"codeExecutionResult": {
"outcome": "OUTCOME_UNSPECIFIED",
"output": "<string>",
"id": "<string>"
},
"executableCode": {
"code": "<string>",
"language": "LANGUAGE_UNSPECIFIED",
"id": "<string>"
},
"fileData": {
"displayName": "<string>",
"fileUri": "<string>",
"mimeType": "<string>"
},
"functionCall": {
"id": "<string>",
"args": {},
"name": "<string>",
"partialArgs": [
{
"boolValue": true,
"jsonPath": "<string>",
"nullValue": "NULL_VALUE",
"numberValue": 123,
"stringValue": "<string>",
"willContinue": true
}
],
"willContinue": true
},
"functionResponse": {
"willContinue": true,
"scheduling": "SCHEDULING_UNSPECIFIED",
"parts": [
{
"inlineData": {
"mimeType": "<string>",
"data": "<string>",
"displayName": "<string>"
},
"fileData": {
"fileUri": "<string>",
"mimeType": "<string>",
"displayName": "<string>"
}
}
],
"id": "<string>",
"name": "<string>",
"response": {}
},
"inlineData": {
"data": "<string>",
"displayName": "<string>",
"mimeType": "<string>"
},
"text": "<string>",
"thought": true,
"thoughtSignature": "<string>",
"videoMetadata": {
"endOffset": "<string>",
"fps": 123,
"startOffset": "<string>"
},
"toolCall": {
"id": "<string>",
"toolType": "TOOL_TYPE_UNSPECIFIED",
"args": {}
},
"toolResponse": {
"id": "<string>",
"toolType": "TOOL_TYPE_UNSPECIFIED",
"response": {}
},
"partMetadata": {}
}
],
"role": "<string>"
},
"groundingMetadata": {
"imageSearchQueries": [
"<string>"
],
"groundingChunks": [
{
"image": {
"sourceUri": "<string>",
"imageUri": "<string>",
"title": "<string>",
"domain": "<string>"
},
"maps": {
"placeAnswerSources": {
"reviewSnippet": [
{
"authorAttribution": {
"displayName": "<string>",
"photoUri": "<string>",
"uri": "<string>"
},
"flagContentUri": "<string>",
"googleMapsUri": "<string>",
"relativePublishTimeDescription": "<string>",
"review": "<string>",
"reviewId": "<string>",
"title": "<string>"
}
],
"flagContentUri": "<string>",
"reviewSnippets": [
{
"authorAttribution": {
"displayName": "<string>",
"photoUri": "<string>",
"uri": "<string>"
},
"flagContentUri": "<string>",
"googleMapsUri": "<string>",
"relativePublishTimeDescription": "<string>",
"review": "<string>",
"reviewId": "<string>",
"title": "<string>"
}
]
},
"placeId": "<string>",
"text": "<string>",
"title": "<string>",
"uri": "<string>",
"route": {
"distanceMeters": 123,
"duration": "<string>",
"encodedPolyline": "<string>"
}
},
"retrievedContext": {
"documentName": "<string>",
"ragChunk": {
"pageSpan": {
"firstPage": 123,
"lastPage": 123
},
"text": "<string>",
"chunkId": "<string>",
"fileId": "<string>"
},
"text": "<string>",
"title": "<string>",
"uri": "<string>",
"customMetadata": [
{
"key": "<string>",
"numericValue": 123,
"stringListValue": {
"values": [
"<string>"
]
},
"stringValue": "<string>"
}
],
"fileSearchStore": "<string>",
"pageNumber": 123,
"mediaId": "<string>"
},
"web": {
"domain": "<string>",
"title": "<string>",
"uri": "<string>"
}
}
],
"groundingSupports": [
{
"confidenceScores": [
123
],
"groundingChunkIndices": [
123
],
"segment": {
"startIndex": 123,
"endIndex": 123,
"partIndex": 123,
"text": "<string>"
},
"renderedParts": [
123
]
}
],
"retrievalMetadata": {
"googleSearchDynamicRetrievalScore": 123
},
"searchEntryPoint": {
"renderedContent": "<string>",
"sdkBlob": "<string>"
},
"webSearchQueries": [
"<string>"
],
"googleMapsWidgetContextToken": "<string>",
"retrievalQueries": [
"<string>"
],
"sourceFlaggingUris": [
{
"flagContentUri": "<string>",
"sourceId": "<string>"
}
]
},
"partial": true,
"turnComplete": true,
"turnCompleteReason": "TURN_COMPLETE_REASON_UNSPECIFIED",
"finishReason": "FINISH_REASON_UNSPECIFIED",
"errorCode": "<string>",
"errorMessage": "<string>",
"interrupted": true,
"customMetadata": {},
"usageMetadata": {
"cacheTokensDetails": [
{
"modality": "MODALITY_UNSPECIFIED",
"tokenCount": 123
}
],
"cachedContentTokenCount": 123,
"candidatesTokenCount": 123,
"candidatesTokensDetails": [
{
"modality": "MODALITY_UNSPECIFIED",
"tokenCount": 123
}
],
"promptTokenCount": 123,
"promptTokensDetails": [
{
"modality": "MODALITY_UNSPECIFIED",
"tokenCount": 123
}
],
"thoughtsTokenCount": 123,
"toolUsePromptTokenCount": 123,
"toolUsePromptTokensDetails": [
{
"modality": "MODALITY_UNSPECIFIED",
"tokenCount": 123
}
],
"totalTokenCount": 123,
"trafficType": "TRAFFIC_TYPE_UNSPECIFIED"
},
"liveSessionResumptionUpdate": {
"newHandle": "<string>",
"resumable": true,
"lastConsumedClientMessageIndex": 123
},
"liveSessionId": "<string>",
"goAway": {
"timeLeft": "<string>"
},
"inputTranscription": {
"text": "<string>",
"finished": true,
"languageCode": "<string>"
},
"outputTranscription": {
"text": "<string>",
"finished": true,
"languageCode": "<string>"
},
"avgLogprobs": 123,
"logprobsResult": {
"chosenCandidates": [
{
"logProbability": 123,
"token": "<string>",
"tokenId": 123
}
],
"topCandidates": [
{
"candidates": [
{
"logProbability": 123,
"token": "<string>",
"tokenId": 123
}
]
}
],
"logProbabilitySum": 123
},
"cacheMetadata": {
"fingerprint": "<string>",
"contents_count": 1,
"cache_name": "<string>",
"expire_time": 123,
"invocations_used": 1,
"created_at": 123
},
"citationMetadata": {
"citations": [
{
"endIndex": 123,
"license": "<string>",
"publicationDate": {
"day": 123,
"month": 123,
"year": 123
},
"startIndex": 123,
"title": "<string>",
"uri": "<string>"
}
]
},
"interactionId": "<string>",
"invocationId": "",
"author": "",
"actions": {
"skipSummarization": true,
"stateDelta": {},
"artifactDelta": {},
"transferToAgent": "<string>",
"escalate": true,
"requestedAuthConfigs": {},
"requestedToolConfirmations": {},
"compaction": {
"startTimestamp": 123,
"endTimestamp": 123,
"compactedContent": {
"parts": [
{
"mediaResolution": {
"level": "MEDIA_RESOLUTION_UNSPECIFIED",
"numTokens": 123
},
"codeExecutionResult": {
"outcome": "OUTCOME_UNSPECIFIED",
"output": "<string>",
"id": "<string>"
},
"executableCode": {
"code": "<string>",
"language": "LANGUAGE_UNSPECIFIED",
"id": "<string>"
},
"fileData": {
"displayName": "<string>",
"fileUri": "<string>",
"mimeType": "<string>"
},
"functionCall": {
"id": "<string>",
"args": {},
"name": "<string>",
"partialArgs": [
{
"boolValue": true,
"jsonPath": "<string>",
"nullValue": "NULL_VALUE",
"numberValue": 123,
"stringValue": "<string>",
"willContinue": true
}
],
"willContinue": true
},
"functionResponse": {
"willContinue": true,
"scheduling": "SCHEDULING_UNSPECIFIED",
"parts": [
{
"inlineData": {
"mimeType": "<string>",
"data": "<string>",
"displayName": "<string>"
},
"fileData": {
"fileUri": "<string>",
"mimeType": "<string>",
"displayName": "<string>"
}
}
],
"id": "<string>",
"name": "<string>",
"response": {}
},
"inlineData": {
"data": "<string>",
"displayName": "<string>",
"mimeType": "<string>"
},
"text": "<string>",
"thought": true,
"thoughtSignature": "<string>",
"videoMetadata": {
"endOffset": "<string>",
"fps": 123,
"startOffset": "<string>"
},
"toolCall": {
"id": "<string>",
"toolType": "TOOL_TYPE_UNSPECIFIED",
"args": {}
},
"toolResponse": {
"id": "<string>",
"toolType": "TOOL_TYPE_UNSPECIFIED",
"response": {}
},
"partMetadata": {}
}
],
"role": "<string>"
}
},
"endOfAgent": true,
"agentState": {},
"rewindBeforeInvocationId": "<string>",
"route": true,
"renderUiWidgets": [
{
"id": "<string>",
"provider": "<string>",
"payload": {}
}
],
"setModelResponse": null
},
"output": null,
"nodeInfo": {
"path": "",
"outputFor": [
"<string>"
],
"messageAsOutput": true
},
"longRunningToolIds": [
"<string>"
],
"branch": "<string>",
"isolationScope": "<string>",
"id": "",
"timestamp": 123
}
],
"lastUpdateTime": 0
}{
"detail": "<string>"
}{
"error": "CONTENT_LENGTH_REQUIRED"
}{
"error": "REQUEST_TOO_LARGE"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Use
stateDelta to update selected state keys; unspecified keys are retained. The service records the state change and returns the updated session without running the agent
This operation changes an existing session, and subsequent invocations use the updated state. Confirm the application, user, session, and values to overwrite before sending the request
Authorizations
Optional locally without a gateway; cloud deployments use the Runtime API key or user-pool JWT required by that deployment, never the model API key
Path Parameters
Application name; harness_agent for the CLI deployment
User ID
Session ID
Body
application/json
Session state changes to apply
Response
Successful response
Last modified on September 19, 2026