---
updatedAt: 2026-04-15T11:43:58.000Z
agentTools:
  projectIndex: https://developers.happeo.com/llms.txt
---

# Update a tool task status

Updates the status, message, and response of a tool task. Used by frontend applications to report tool execution results or status changes.

This endpoint only updates the tool task and returns the updated task as JSON. It does not trigger AI responses.

To update a tool task AND trigger AI continuation, use the POST /chats/{discussionId}/tool-tasks/{toolTaskId} endpoint instead.


# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Chat API",
    "version": "1.0",
    "description": "Chat API for managing discussions, entries, tool tasks, and AI conversations with streaming responses."
  },
  "tags": [
    {
      "name": "Chat",
      "description": "Chat system endpoints for managing discussions, entries, and AI conversations"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-universe-auth"
      }
    },
    "schemas": {
      "ToolTask": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the tool task"
          },
          "entryId": {
            "type": "string",
            "description": "ID of the entry that initiated this tool task"
          },
          "status": {
            "$ref": "#/components/schemas/ToolTaskStatus"
          },
          "name": {
            "type": "string",
            "description": "Name of the tool that was called"
          },
          "args": {
            "type": "object",
            "description": "Arguments passed to the tool"
          },
          "isToolCall": {
            "type": "boolean",
            "description": "Whether this is a tool call (true) or a frontend function (false)"
          },
          "response": {
            "type": "string",
            "description": "Stringified JSON response from the tool execution. Can be updated multiple times as the task progresses."
          },
          "sessionId": {
            "type": "string",
            "description": "Session ID for tracking interactions within a single session"
          },
          "_links": {
            "$ref": "#/components/schemas/ToolTaskLinks"
          }
        }
      },
      "ToolTaskStatus": {
        "type": "object",
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "submitted",
              "working",
              "input-required",
              "completed",
              "canceled",
              "failed"
            ],
            "description": "Current state of the tool task"
          },
          "message": {
            "type": "string",
            "description": "Human readable message providing details about the current status",
            "nullable": true
          },
          "timestamp": {
            "type": "integer",
            "description": "Timestamp when this status was set"
          }
        }
      },
      "ToolTaskLinks": {
        "type": "object",
        "properties": {
          "self": {
            "type": "string",
            "description": "Link to this tool task"
          },
          "urn:happeo:rel:update": {
            "type": "string",
            "description": "Link to update this tool task (includes sessionId query param when available)"
          },
          "urn:happeo:rel:continue": {
            "type": "string",
            "description": "Link to continue conversation with this tool task result (includes sessionId query param when available)"
          }
        }
      },
      "UpdateToolTaskDTO": {
        "type": "object",
        "required": [
          "state"
        ],
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "submitted",
              "working",
              "input-required",
              "completed",
              "canceled",
              "failed"
            ],
            "description": "New state for the tool task"
          },
          "message": {
            "type": "string",
            "description": "Optional status message"
          },
          "response": {
            "type": "string",
            "description": "Tool execution response (required when state is completed)"
          }
        }
      }
    }
  },
  "paths": {
    "/chats/{discussionId}/tool-tasks/{toolTaskId}": {
      "put": {
        "summary": "Update a tool task status",
        "description": "Updates the status, message, and response of a tool task. Used by frontend applications to report tool execution results or status changes.\n\nThis endpoint only updates the tool task and returns the updated task as JSON. It does not trigger AI responses.\n\nTo update a tool task AND trigger AI continuation, use the POST /chats/{discussionId}/tool-tasks/{toolTaskId} endpoint instead.\n",
        "tags": [
          "Chat"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "discussionId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The unique identifier of the discussion"
          },
          {
            "in": "path",
            "name": "toolTaskId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The unique identifier of the tool task"
          },
          {
            "in": "header",
            "name": "x-universe-auth",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "JWT authentication token"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateToolTaskDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool task updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToolTask"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed or error updating tool task"
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication"
          },
          "404": {
            "description": "Discussion or tool task not found"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ]
}
```