---
title: "Rehydrate Task"
method: POST
path: "/tasks/{task_id}/rehydrate"
tags: ["task-retention"]
---

# Rehydrate Task

`POST /tasks/{task_id}/rehydrate`

Restore content-bearing rows from a snapshot.

Two modes:
- Inline: caller provides messages and task_states in the request body.
- URL: caller provides snapshot_url; Agentex downloads and parses it.

Refuses if the task isn't currently in a cleaned state, or if any supplied
message/state ID already exists in Mongo (catches double-rehydrate).

## Path parameters

- `task_id` string, required

## Request body

- RehydrateTaskRequest — Either provide inline content (messages + task_states) or a snapshot_url pointing at a presigned JSON download. Mixing both is rejected. The inline form is the canonical shape used by export's GET response, so snapshot → clean → rehydrate round-trips cleanly without serialization changes.
  - `task_id` string, required
  - `messages` TaskMessageEntity[]
    - `id` string, nullable — The task message's unique id
    - `task_id` string, required — ID of the task this message belongs to
    - `content` union, required — The content of the message. This content is not OpenAI compatible. These are messages that are meant to be displayed to the user.
      - TextContentEntity
        - `type` 'text' — The type of the message, in this case `text`.
        - `author` 'user' | 'agent', required
        - `style` 'static' | 'active'
        - `format` 'markdown' | 'plain' | 'code'
        - `content` string, required — The contents of the text message.
        - `attachments` FileAttachmentEntity[], nullable — Optional list of file attachments with structured metadata.
          - `file_id` string, required — The unique ID of the attached file
          - `name` string, required — The name of the file
          - `size` integer, required — The size of the file in bytes
          - `type` string, required — The MIME type or content type of the file
      - DataContentEntity
        - `type` 'data' — The type of the message, in this case `data`.
        - `author` 'user' | 'agent', required
        - `style` 'static' | 'active'
        - `data` object, required — The contents of the data message.
      - ToolRequestContentEntity
        - `type` 'tool_request' — The type of the message, in this case `tool_request`.
        - `author` 'user' | 'agent', required
        - `style` 'static' | 'active'
        - `tool_call_id` string, required — The ID of the tool call that is being requested.
        - `name` string, required — The name of the tool that is being requested.
        - `arguments` object, required — The arguments to the tool.
      - ToolResponseContentEntity
        - `type` 'tool_response' — The type of the message, in this case `tool_response`.
        - `author` 'user' | 'agent', required
        - `style` 'static' | 'active'
        - `tool_call_id` string, required — The ID of the tool call that is being responded to.
        - `name` string, required — The name of the tool that is being responded to.
        - `content` unknown, required
        - `is_error` boolean, nullable — Whether the tool call resulted in an error. `None` when the harness does not report a status.
      - ReasoningContentEntity
        - `type` 'reasoning' — The type of the message, in this case `reasoning`.
        - `author` 'user' | 'agent', required
        - `style` 'static' | 'active'
        - `summary` string[], required — A list of short reasoning summaries
        - `content` string[], nullable — The reasoning content or chain-of-thought text
    - `streaming_status` 'IN_PROGRESS' | 'DONE', nullable
    - `created_at` string, date-time, nullable — The timestamp when the message was created
    - `updated_at` string, date-time, nullable — The timestamp when the message was last updated
  - `task_states` StateEntity[]
    - `id` string, nullable — The task state's unique id
    - `task_id` string, required — ID of the task this state belongs to. The combination of task_id and agent_id is globally unique.
    - `agent_id` string, required — ID of the agent this state belongs to. The combination of task_id and agent_id is globally unique.
    - `state` object, required — The state object that contains arbitrary data
    - `created_at` string, date-time, nullable — The timestamp when the state was created
    - `updated_at` string, date-time, nullable — The timestamp when the state was last updated
  - `snapshot_url` string, uri, nullable — Presigned GET URL whose body is a JSON-encoded TaskSnapshotEntity. Must be https; must resolve to a public address. When set, messages/task_states must be empty.

## Response `204`

Successful Response

## Other responses

- `422` — Validation Error

## Changes

> 55 revisions in range; 1 could not be searched.

- **2026-07-10** `fbecbdbd7dc5` — 1 info
  - added the new optional request property `messages/items/content/oneOf[subschema #4: ToolResponseContentEntity]/is_error`
- **2026-06-23** `94d73d46952b` — 1 warning
  - removed the request property `messages/items/content/oneOf[subschema #4: ToolResponseContentEntity]/is_error`
- **2026-06-22** `28b893025743` — 1 info
  - added the new optional request property `messages/items/content/oneOf[subschema #4: ToolResponseContentEntity]/is_error`
- **2026-05-29** `12a516f4d9ac` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/scaleapi/apis/agentex-api/changes/tasks/:task_id/rehydrate/post.md)

---

[API](https://skmtc.dev/scaleapi/apis/agentex-api.md) · [All operations](https://skmtc.dev/scaleapi/apis/agentex-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/scaleapi/agentex-api/revisions/1e0aaafd5780/schema)