---
title: "POST /v1/todos/sync"
method: POST
path: "/v1/todos/sync"
tags: ["TodoService"]
---

# POST /v1/todos/sync

`POST /v1/todos/sync`

SyncTodos opens a bidirectional stream for two-way synchronization.
 The client sends SyncTodoRequest messages describing local changes, and
 the server pushes back TodoEvent messages reflecting the resulting state.
 The stream stays open until either side closes it.

## Request body

- TodoV1SyncTodoRequest — SyncTodoRequest is a single client message in the SyncTodos bidirectional stream. The action field selects which operation to perform on the server.
  - `action` string — The operation to perform. One of `create`, `update`, or `delete`.
  - `todo` TodoV1Todo — Todo is the canonical representation of a todo item.
    - `id` string — Application-generated UUIDv7 identifier. Read-only on create.
    - `title` string — Short human-readable title.
    - `content` string — Detailed description or notes for the todo item.
    - `completed` boolean — Whether the todo item has been completed.
    - `createdAt` string, date-time — Time at which the todo item was created. Server-assigned, read-only.
    - `updatedAt` string, date-time — Time at which the todo item was last modified. Server-assigned, read-only.
    - `status` integer — Lifecycle state. Server-assigned, read-only: call DeleteTodo to move an item to TODO_STATUS_DELETED.
  - `id` string — Identifier of the target todo. Required for `delete` and `update`.
  - `updateMask` string, field-mask — Field mask used by `update` actions to limit which fields are overwritten. Ignored for `create` and `delete`.

## Response `200`

OK

- TodoV1TodoEvent — TodoEvent is a server-sent message describing a change to a todo item. It is emitted by both WatchTodos and SyncTodos streams.
  - `action` string — The change that occurred. One of `created`, `updated`, or `deleted`.
  - `todo` TodoV1Todo — Todo is the canonical representation of a todo item.
    - `id` string — Application-generated UUIDv7 identifier. Read-only on create.
    - `title` string — Short human-readable title.
    - `content` string — Detailed description or notes for the todo item.
    - `completed` boolean — Whether the todo item has been completed.
    - `createdAt` string, date-time — Time at which the todo item was created. Server-assigned, read-only.
    - `updatedAt` string, date-time — Time at which the todo item was last modified. Server-assigned, read-only.
    - `status` integer — Lifecycle state. Server-assigned, read-only: call DeleteTodo to move an item to TODO_STATUS_DELETED.
  - `eventTime` string, date-time — Time at which the change was observed by the server.

## Changes

- **2026-08-15** `bbd5b5339910` — 4 warning, 6 info
  - removed the request property `todo/allOf[#/components/schemas/todo.v1.Todo]/createTime`
  - removed the request property `todo/allOf[#/components/schemas/todo.v1.Todo]/updateTime`
  - removed the optional property `todo/allOf[#/components/schemas/todo.v1.Todo]/createTime` from the response with the `200` status
  - removed the optional property `todo/allOf[#/components/schemas/todo.v1.Todo]/updateTime` from the response with the `200` status
  - …6 more
- **2026-06-18** `d99daada47f9` — 1 info
  - endpoint added
- **2021-12-27** `52ca3c9327fd` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/go-kratos/apis/todoservice-api/changes/v1/todos/sync/post.md)

---

[API](https://skmtc.dev/go-kratos/apis/todoservice-api.md) · [All operations](https://skmtc.dev/go-kratos/apis/todoservice-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/go-kratos/todoservice-api/revisions/bbd5b5339910/schema)