--- title: "Get Sync" method: GET path: "/v1/sync" tags: ["sync"] --- # Get Sync `GET /v1/sync` ## Request - Base URL: `https://app.tokumalabs.com/api` - URL: `https://app.tokumalabs.com/api/v1/sync` - Auth: OAuth 2 - Password - Token URL: `v1/auth/token` Return rows changed since the cursor for every cursor-synced resource. ## Query parameters - `since` string, nullable: Opaque cursor blob from the previous response's `next_since`. Omit or pass empty for cold-start (returns everything for the user). - `limit` integer: Per-resource page size (default 500, max 2000). ## Response `200` Successful Response - SyncResponse: Cursor sync response envelope. - `rows` SyncRows, required: Per-resource row buckets returned by ``/api/v1/sync``. - `time_block` TimeBlockSyncDto[] - `id` integer, required - `organization_id` string, required - `user_id` string, required - `start_time` string, date-time, required - `end_time` string, date-time, required - `headline` string, required - `is_live` boolean, required - `app_id` string, nullable - `app_name` string, nullable - `segment_id` string, nullable - `matter_segment` MatterSegmentSummaryDto: Summary of matter and segment for time blocks. - `matter_id` string, required: Matter ID - `matter_name` string, required: Matter name - `segment_id` string, required: Segment ID - `segment_name` string, required: Segment name - `segment_order` integer, required: Display order of the segment within the matter - `is_root` boolean, required: Whether this is the root segment - `root_segment_id` string, nullable: Root segment ID of the matter - `activity_code` string, nullable - `time_entry_id` integer, nullable - `source_type` 'APP' | 'MS365_CALL' | 'MS365_EMAIL' | 'MS365_CALENDAR_EVENT', required: Source of a time block. - `headline_attempt_status` 'not_attempted' | 'succeeded' | 'skipped_no_signal' | 'failed_terminal': Vocabulary for `time_blocks.headline_attempt_status`. Stored as a `(str, Enum)` so the cursor-sync wire DTO can type the field as the enum and Pydantic v2 serializes to the bare value ('not_attempted' etc.) — the qualified-name footgun of plain `str(EnumMember)` is avoided. - `artifacts` BlockArtifactsDto: Artifacts for one block: a capped list plus the honest total. ``total`` is the pre-cap count of displayed (doc+email) artifacts — the same population as ``items`` — so a client showing the first N can render an honest "+more" without the wire ever implying the capped list is complete. - `items` ArtifactDto[] - `kind` 'doc' | 'email', required - `title` string, required - `location` string, nullable - `total` integer - `created_at` string, date-time, required - `updated_at` string, date-time, required - `deleted_at` string, date-time, nullable - `version` integer, required - `time_entry` TimeEntrySyncDto[] - `id` integer, required - `organization_id` string, required - `user_id` string, required - `date` string, date, required - `legal_time_minutes` integer, required - `legal_time_is_computed` boolean, required - `tracked_duration_minutes` integer, required - `narrative` string, nullable, required - `narrative_suggestions` string[], nullable - `activity_code` string, nullable - `segment_id` string, nullable - `matter_segment` MatterSegmentSummaryDto: Summary of matter and segment for time blocks. - `matter_id` string, required: Matter ID - `matter_name` string, required: Matter name - `segment_id` string, required: Segment ID - `segment_name` string, required: Segment name - `segment_order` integer, required: Display order of the segment within the matter - `is_root` boolean, required: Whether this is the root segment - `root_segment_id` string, nullable: Root segment ID of the matter - `is_billable` boolean, required - `legal_time_pinned` boolean, required - `legal_time_resnapped_from` integer, nullable - `is_user_created` boolean, required - `created_at` string, date-time, required - `updated_at` string, date-time, required - `deleted_at` string, date-time, nullable - `version` integer, required - `time_entry_release` TimeEntryReleaseSyncDto[] - `id` integer, required - `organization_id` string, required - `user_id` string, required - `time_entry_id` integer, required - `released_at` string, date-time, required - `export_id` integer, nullable - `created_at` string, date-time, required - `updated_at` string, date-time, required - `version` integer, required - `generation_task` GenerationTaskSyncDto[] - `id` string, required - `organization_id` string, required - `user_id` string, required - `date` string, date, required - `status` string, required - `phase` string, nullable - `is_rebuild` boolean - `error_code` string, nullable - `error` string, nullable - `retry_count` integer, required - `last_error_code` string, nullable - `last_error` string, nullable - `created_at` string, date-time, required - `updated_at` string, date-time, required - `version` integer, required - `user_settings` UserSettingsSyncDto[] - `user_id` string, required - `organization_id` string, required - `timezone` string, required - `target_per_day_minutes` integer, nullable - `week_start_day` integer, required - `fiscal_year_start_month` integer, required - `fiscal_year_start_day` integer, required - `time_display_format` string, required - `activity_codes_enabled` boolean, required - `default_billing_increment_minutes` integer - `default_billing_rounding_rule` string - `decimal_places` integer - `updated_at` string, date-time, required - `version` integer, required - `client` ClientSyncDto[] - `id` string, required - `organization_id` string, required - `name` string, required - `is_active` boolean, required - `created_at` string, date-time, required - `updated_at` string, date-time, required - `deleted_at` string, date-time, nullable - `version` integer, required - `matter` MatterSyncDto[] - `id` string, required - `organization_id` string, required - `client_id` string, required - `name` string, required - `external_id` string, nullable - `status` string - `closed_at` string, date-time, nullable - `billing_increment_minutes` integer - `billing_rounding_rule` string - `created_at` string, date-time, required - `updated_at` string, date-time, required - `deleted_at` string, date-time, nullable - `version` integer, required - `segment` SegmentSyncDto[] - `id` string, required - `organization_id` string, required - `matter_id` string, required - `name` string, required - `is_root` boolean, required - `is_billable` boolean, required - `is_active` boolean, required - `order` integer, required - `created_at` string, date-time, required - `updated_at` string, date-time, required - `deleted_at` string, date-time, nullable - `version` integer, required - `next_since` string, required: Opaque cursor blob to send back as `since` on the next call. - `has_more` boolean, required: True when at least one resource hit its per-resource limit on this page; the client should immediately call again with `next_since`. - `server_time` string, date-time, required: Server's wall-clock when the response was assembled. Diagnostic only — never used as a cursor. - `reset` string[]: Resources the client must wipe locally **before** applying this page. Sent when what the caller may see has changed: the feed has no tombstone for a row that was withdrawn rather than deleted, so cold-starting the slot alone would leave the withdrawn rows in place. Empty on virtually every round. ## Other responses - `400`: Validation error or domain rule violation. - `401`: Missing, expired, or invalid authentication. - `403`: Authenticated but not permitted. - `404`: Resource not found. - `409`: Resource state conflict (duplicate, illegal transition). - `422`: Request body failed schema validation. - `500`: Server-side failure. --- [API](https://skmtc.dev/tokumalabs/apis/tokuma-user-api.md) - [All operations](https://skmtc.dev/tokumalabs/apis/tokuma-user-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tokumalabs/apis/tokuma-user-api/revisions/1f8201af459b?raw)