> ## Documentation Index > Fetch the complete documentation index at: https://task-social.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Agent-Oriented Task Update > Operational guidance for AI systems that need to understand when and how to update a TaskSocial task. # Agent-Oriented Task Update This guide provides operational instructions for an AI system or agent that needs to understand how to update a TaskSocial task. The API reference describes the technical contract of an operation, including the endpoint, HTTP method, parameters, request body, and response codes. This guide adds another layer of context. It explains: * When the operation should be used * When it should not be used * What conditions should be checked first * What information is required * What side effects the operation has * How an AI system should handle ambiguity * How an AI system should respond to common errors ## Operation **Tool concept:** `update_task` **Underlying API endpoint:** `PUT /api/v1/tasks/{id}` ## Purpose Use this operation to update an existing TaskSocial task. A task may have its: * Title updated * Description updated * Status changed The technical API allows an authenticated task owner to modify their existing task. ## When to use this operation Use the update operation when all of the following conditions are true: * The authenticated user explicitly wants to modify an existing task. * The target task can be identified. * The task ID is available. * The authenticated user owns the task. * At least one valid field needs to be updated. For example: > Change my task title to "Finish the TaskSocial documentation." Or: > Mark my documentation task as completed. In these cases, the user's intention is to modify an existing task. ## When not to use this operation Do not use the update operation when: * The user is only asking for information about a task. * The user wants to create a new task. * The user wants to delete a task. * The target task is unclear. * Multiple tasks could match the user's request. * The requested change is unclear or ambiguous. * The authenticated user does not own the task. For example: > Update my task. This request does not clearly identify the task or explain what should be changed. The agent should ask for clarification instead of making an arbitrary update. ## Preconditions Before updating a task, the following conditions should be checked: 1. The user is authenticated. 2. The target task can be identified. 3. The task ID is available. 4. The authenticated user owns the task. 5. At least one valid field is provided for the update. If these conditions are not satisfied, the agent should not blindly perform the operation. ## Required input The operation requires the following path parameter: | Input | Type | Required | Description | | ----- | ------ | -------- | -------------------------------------- | | `id` | string | Yes | MongoDB ObjectId of the task to update | ## Optional input The request body may contain one or more of the following fields: | Field | Type | Description | | ------------- | ------ | ------------------------------------- | | `title` | string | New title for the task | | `description` | string | New description for the task | | `status` | string | Task status: `pending` or `completed` | At least one valid field should be provided when performing an update. ## Example request ```json theme={null} { "title": "Finish TaskSocial documentation", "status": "completed" } ``` ## Expected result If the update is successful, the API returns a `200 OK` response. The response contains the updated task. ## Possible errors | Status | Meaning | Recommended agent behavior | | -------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------- | | `403` | The authenticated user does not own the task | Do not retry the same update. Inform the user that they cannot update a task they do not own. | | `404` | The task does not exist | Do not retry with the same task ID. Inform the user that the task could not be found. | | Authentication error | The user is not authenticated | Ask the user to authenticate before attempting an authenticated operation again. | ## Side effects This operation modifies existing data. Depending on the request, it can change: * The task title * The task description * The task status Because the operation changes stored data, the intended task and requested changes should be clear before calling the API. ## Handling ambiguity Explicit confirmation is not necessarily required for every update, but the requested action should be clear. For example: > Mark task 123 as completed. The target task and requested change are clear. However, consider this request: > Update my documentation task. The agent may not know: * Which documentation task the user means * What field should be changed * What the new value should be If multiple tasks could match the request, the agent should ask the user for clarification. The agent should not choose a task arbitrarily. For example: > Which task would you like to update, and what would you like to change? ## Recommended decision process Before calling the update operation, an AI system can follow this process: ```text theme={null} User requests a task update ↓ Is the user authenticated? ↓ Can the target task be identified? ↓ Does the user own the task? ↓ Are the requested changes clear? ↓ Are the update fields valid? ↓ Call PUT /api/v1/tasks/{id} ↓ Return the result to the user ``` ## Example scenarios ### Scenario 1: Clear request User: > Mark my task with ID 123 as completed. The agent can: 1. Verify that the user is authenticated. 2. Identify task ID `123`. 3. Attempt to update the `status` field to `completed`. 4. Return the result of the operation. ### Scenario 2: Ambiguous request User: > Update my task. The agent should not immediately call the update operation. Instead, it should ask: > Which task would you like to update, and what would you like to change? The operation should only be performed after the intended task and requested changes are clear. ### Scenario 3: User does not own the task If the API returns: ```text theme={null} 403 Forbidden ``` The agent should explain that the authenticated user does not have permission to update that task. It should not repeatedly retry the same operation. ### Scenario 4: Task does not exist If the API returns: ```text theme={null} 404 Not Found ``` The agent should inform the user that the task could not be found. The agent can then ask the user to provide or identify the correct task. ## Traditional API documentation A traditional API reference focuses on the technical contract. For this operation, it answers questions such as: * Which endpoint should be called? * Which HTTP method is used? * What path parameter is required? * What request body fields are accepted? * What responses can be returned? For example: ```text theme={null} PUT /api/v1/tasks/{id} ``` This information is essential for a developer or system that needs to technically call the API. ## Agent-oriented documentation Agent-oriented documentation adds operational context. It answers additional questions such as: * When should this operation be used? * When should it not be used? * What conditions should be checked first? * What should happen when the user's request is ambiguous? * What should the agent do after receiving an error? * What data does the operation modify? This additional context helps describe not only **how to call an API**, but also **how an AI system should reason about whether it should call the API**. ## The relationship between the two OpenAPI describes the technical contract. The API reference presents that contract in a format developers can read and interact with. Agent-oriented documentation adds operational instructions, business context, preconditions, and guidance about how an AI system should behave. Together, the documentation can be viewed as: ```text theme={null} OpenAPI + API reference + Human-readable guides + Business rules + Preconditions + Error-handling guidance + Operational instructions ↓ More complete documentation for humans and AI systems ``` ## Key idea OpenAPI tells a system what an API technically accepts. Agent-oriented documentation adds context about when the operation should be used, when it should not be used, and what should happen before and after the operation. This does not turn TaskSocial into an autonomous AI agent. Instead, it is an experiment showing how documentation can move beyond endpoint descriptions and include the operational context that an AI system may need before taking an action. View the technical API contract, request parameters, request body, and response codes for updating a TaskSocial task.