> ## Documentation Index > Fetch the complete documentation index at: https://docs.tela.com/llms.txt > Use this file to discover all available pages before exploring further. # Update a task > Updates a task’s name, tags, output, or approves it. ## OpenAPI ````yaml PATCH /task/{id} openapi: 3.0.1 info: title: Tela API license: name: MIT version: 1.0.0 servers: - url: https://api.tela.com security: [] paths: /task/{id}: patch: tags: - Task summary: Update a task description: > Updates a task's name, tags, output, or approves it. - `status: "completed"` approves the task: `approvedBy` is set to the caller's email, `approvedAt` to now, and any previous approval revocation is cleared. Approving a Workstation/App task also fires the app's `task.approved` webhooks. `completed` is the only status accepted. - `outputContent` for Workstation/App tasks is deep-merged into the current output; every changed path is recorded in `metadata.editedFields` and a task version snapshot is stored. For agent tasks the value replaces the stored output as-is. - Returns 400 (`UPDATE_FAILED`) while the task is still `running`. parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TaskUpdateRequest' examples: Approve: value: status: completed Edit output and tags: value: outputContent: content: cliente: Acme Corporation tags: - priority - reviewed responses: '200': description: The updated task content: application/json: schema: $ref: '#/components/schemas/Task' example: id: 8b6d2c9a-1f4e-4c1b-9a1e-3c2d5e6f7a80 reference: 42 name: Invoice-2025-001.pdf status: completed rawInput: application_id: 95cec438-6080-44fe-8275-28b16bd40178 variables: document: files: - file_url: https://example.com/invoice.pdf inputContent: variables: document: files: - file_url: https://example.com/invoice.pdf messages: [] files: [] outputContent: role: assistant content: cliente: Acme Corporation valor: 150000 originalOutputContent: role: assistant content: cliente: Acme Corp valor: 150000 createdBy: api@company.com approvedBy: reviewer@company.com approvedAt: '2025-01-15T11:00:00.000Z' completionRunId: b83b1558-de5b-4e45-b517-7bececbdd154 workflowRunId: null sourceType: prompt agentId: null agentRef: null agentSessionId: null promptVersionId: 76065caa-c519-441a-8fe2-cc43e29664ab promptApplicationId: 95cec438-6080-44fe-8275-28b16bd40178 workspaceId: 3f55cfd9-4427-4887-a181-d9ad39967802 metadata: editedFields: - path: cliente author: reviewer@company.com editedAt: '2025-01-15T11:00:00.000Z' previousValue: Acme Corp tags: - priority - reviewed createdAt: '2025-01-15T10:30:00.000Z' updatedAt: '2025-01-15T11:00:00.000Z' deletedAt: null '400': description: Invalid payload, or the task is still running (`UPDATE_FAILED`) content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Task not found content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: TaskUpdateRequest: type: object title: Task update properties: name: type: string status: type: string description: >- Only `completed` is accepted; it approves the task on behalf of the caller. enum: - completed outputContent: type: object nullable: true additionalProperties: true description: >- Output changes, e.g. `{ "content": { "field": "new value" } }`. Deep-merged into the existing output for Workstation/App tasks; replaces it for agent tasks. tags: type: array items: type: string description: Replaces the task's tags (trimmed, de-duplicated). Task: type: object title: Task properties: id: type: string format: uuid reference: type: integer nullable: true description: >- Sequential number of the task within its app/agent. Assigned shortly after creation. name: type: string status: $ref: '#/components/schemas/TaskStatus' rawInput: $ref: '#/components/schemas/TaskRawInput' inputContent: $ref: '#/components/schemas/TaskInputContent' outputContent: type: object nullable: true additionalProperties: true description: >- Current output. For Canvas tasks this is the assistant message (`role`, `content`, …) where `content` holds the extracted fields; for workflow tasks it wraps `{ response, stepOutputs, error? }`. Reflects reviewer edits. originalOutputContent: type: object nullable: true additionalProperties: true description: >- Output as originally produced by the execution, before any reviewer edits. createdBy: type: string description: Email of the identity that created the task. approvedBy: type: string nullable: true approvedAt: type: string format: date-time nullable: true completionRunId: type: string format: uuid nullable: true workflowRunId: type: string format: uuid nullable: true sourceType: $ref: '#/components/schemas/TaskSourceType' agentId: type: string format: uuid nullable: true agentRef: type: string nullable: true description: Published agent identifier (agent tasks only). agentSessionId: type: string nullable: true promptVersionId: type: string format: uuid nullable: true description: >- Canvas version the task was executed with (Workstation/App tasks only). promptApplicationId: type: string format: uuid nullable: true workspaceId: type: string format: uuid metadata: $ref: '#/components/schemas/TaskMetadata' tags: type: array items: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time deletedAt: type: string format: date-time nullable: true inputFiles: type: array description: >- Only present on `GET /task` when `excludeInputOutputColumns=true` (and `excludeInputFiles` is not set). Summary of `inputContent.files` without parser payloads. items: type: object properties: name: type: string filename: type: string type: type: string url: type: string mimeType: type: string jobId: type: string pages: type: number usedAt: type: string enum: - variables - messages required: - id - name - status - createdBy - sourceType - workspaceId - tags - createdAt - updatedAt Error: {} TaskStatus: type: string description: >- Task lifecycle status. `created` (agent tasks awaiting execution) → `running` → `validating` (output ready, awaiting review) → `completed` (approved). `failed` and `cancelled` are terminal. enum: - created - running - validating - completed - failed - cancelled TaskRawInput: type: object nullable: true title: Raw input description: >- The completion request the task is executed with. Same shape as the `/v2/chat/completions` body; `application_id` is set by the server from `promptApplicationId`. properties: application_id: type: string format: uuid description: >- Set by the server; any value you send is overwritten with `promptApplicationId`. canvas_id: type: string format: uuid version_id: type: string format: uuid environment_name: type: string variables: type: object description: >- Variables keyed by the app's variable names. Files are passed here (see `TaskVariableValue`). additionalProperties: $ref: '#/components/schemas/TaskVariableValue' messages: type: array items: $ref: '#/components/schemas/TaskMessage' input: type: string webhook_url: type: string description: URL that receives a POST when the execution finishes. override: $ref: '#/components/schemas/Override' stream: type: boolean async: type: boolean long_response: type: boolean label: type: string tags: type: array items: type: string TaskInputContent: type: object nullable: true title: Input content description: >- Normalized input of the execution. `null` until the run has been prepared. properties: variables: type: object additionalProperties: $ref: '#/components/schemas/TaskInternalVariableContent' messages: type: array items: $ref: '#/components/schemas/TaskMessage' files: type: array items: $ref: '#/components/schemas/TaskInputFile' TaskSourceType: type: string description: >- Whether the task belongs to a Workstation/App (`prompt`) or to an agent (`agent`). enum: - prompt - agent TaskMetadata: type: object nullable: true title: Task metadata properties: resourceContext: $ref: '#/components/schemas/TaskResourceContext' editedFields: type: array description: >- Paths inside `outputContent.content` edited by reviewers via `PATCH /task/{id}`. items: type: object properties: path: type: string author: type: string editedAt: type: string format: date-time previousValue: {} required: - path - author - editedAt approvalRevokedBy: type: string approvalRevokedAt: type: string format: date-time sourceFile: type: object description: Provenance of tasks created from a spreadsheet/CSV import. properties: filename: type: string mimeType: type: string fileSize: type: number totalRows: type: number rowIndex: type: number uploadedAt: type: string format: date-time uploadedBy: type: string required: - filename TaskVariableValue: description: >- Value of a variable when creating a task. A string for text variables; a file object for a single file; `{ files: [...] }` for several files; `{ text, files }` for mixed content. oneOf: - type: string title: Text - $ref: '#/components/schemas/TaskVariableFile' - type: object title: Files properties: files: type: array items: $ref: '#/components/schemas/TaskVariableFile' required: - files - type: object title: Mixed properties: text: oneOf: - type: string - type: object additionalProperties: type: string files: type: array items: $ref: '#/components/schemas/TaskVariableFile' required: - text - files TaskMessage: type: object properties: role: type: string content: description: A string, a single content part, or an array of content parts. oneOf: - type: string - $ref: '#/components/schemas/TaskMessageContentPart' - type: array items: $ref: '#/components/schemas/TaskMessageContentPart' function_call: type: object properties: name: type: string arguments: type: string required: - name - arguments required: - role - content Override: type: object description: >- Override default settings specified in the canvas. This allows for fine-tuning the completion behavior for this specific request. properties: model: type: string description: >- The specific model to use for this completion. If not specified, the default model set in the canvas will be used. temperature: type: number description: >- Controls randomness in the output. Values between 0 and 1. Lower values make the output more focused and deterministic. type: type: string enum: - chat - completion description: Specifies whether to use a chat or completion model. functions: type: array items: type: object properties: id: type: string name: type: string description: type: string parameters: type: object properties: type: type: string enum: - object properties: type: object additionalProperties: true required: type: array items: type: string description: >- An array of functions that the model can call. This allows for more structured and interactive completions. structured_output: type: object properties: enabled: type: boolean description: Whether to enable structured output for this completion. schema: type: object properties: properties: type: object additionalProperties: true description: Defines the properties of the structured output type: type: string enum: - object description: >- The type of the schema, always "object" for structured output title: type: string description: The title of the schema description: type: string description: A description of the schema required: type: array items: type: string description: An array of required property names description: >- The schema defining the structure of the output. This is used when structured output is enabled. description: Configuration for generating structured output. required: - type TaskInternalVariableContent: description: >- Normalized variable value as stored on the task. A string, `{ files: [...] }`, or `{ text, files }` (a single file object is normalized into `files`). oneOf: - type: string - type: object properties: files: type: array items: $ref: '#/components/schemas/TaskVariableFile' required: - files - type: object properties: text: oneOf: - type: string - type: object additionalProperties: type: string files: type: array items: $ref: '#/components/schemas/TaskVariableFile' required: - text - files TaskInputFile: type: object description: >- A file that took part in the execution, either from a variable (`usedAt: variables`) or from a message (`usedAt: messages`). properties: name: type: string description: Variable name, or `message-{index}` for files found in messages. type: type: string usedAt: type: string enum: - variables - messages url: type: string mimeType: type: string jobId: type: string description: Parser job identifier, when the file was parsed. filename: type: string pages: type: number parserData: type: object additionalProperties: true description: Parser result payload (structure not documented here). filePagesAsImage: type: array items: type: string TaskResourceContext: type: object description: >- Set by the server on tasks that run against a resource shared from another workspace (federated). Client-supplied values are discarded. properties: isFederated: type: boolean entitlementId: type: string nullable: true executionWorkspaceId: type: string billingWorkspaceId: type: string resourceWorkspaceId: type: string credentialWorkspaceId: type: string projectId: type: string nullable: true TaskVariableFile: type: object title: File properties: file_url: type: string description: Publicly reachable URL or a `vault://` reference of the file. file_name: type: string mime_type: type: string vault_reference: type: string options: type: object properties: range: type: array description: Page range to process (e.g. for PDFs). items: type: number required: - file_url TaskMessageContentPart: oneOf: - type: object title: Text part properties: type: type: string enum: - text text: type: string required: - type - text - type: object title: Image part properties: type: type: string enum: - image_url image_url: type: object properties: url: type: string detail: type: string enum: - auto - high - low required: - url required: - type - image_url securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT or UUID ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.