From 7abd625af305b82a4d37b578ffc535c3d7d302dc Mon Sep 17 00:00:00 2001
From: Alan Grainger <16197738+alangrainger@users.noreply.github.com>
Date: Sat, 12 Sep 2026 06:50:08 +1200
Subject: [PATCH] docs(server): document the UTC timestamp format for
 timeBucket (#31421)

* docs(server): document the UTC timestamp format for timeBucket

* docs(server): wrap timeBucket description to satisfy prettier
---
 open-api/immich-openapi-specs.json | 4 ++--
 server/src/dtos/time-bucket.dto.ts | 5 ++++-
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/open-api/immich-openapi-specs.json b/open-api/immich-openapi-specs.json
index cb9e32ffd..a8028f6bc 100644
--- a/open-api/immich-openapi-specs.json
+++ b/open-api/immich-openapi-specs.json
@@ -15946,9 +15946,9 @@
             "name": "timeBucket",
             "required": true,
             "in": "query",
-            "description": "Time bucket identifier in YYYY-MM-DD format",
+            "description": "Time bucket identifier in YYYY-MM-DDT00:00:00.000Z format",
             "schema": {
-              "example": "2024-01-01",
+              "example": "2024-01-01T00:00:00.000Z",
               "type": "string"
             }
           },
diff --git a/server/src/dtos/time-bucket.dto.ts b/server/src/dtos/time-bucket.dto.ts
index a958d62e1..8399d81f4 100644
--- a/server/src/dtos/time-bucket.dto.ts
+++ b/server/src/dtos/time-bucket.dto.ts
@@ -66,7 +66,10 @@ const TimeBucketQueryBaseSchema = z
 
 const TimeBucketSchema = TimeBucketQueryBaseSchema;
 const TimeBucketAssetSchema = TimeBucketQueryBaseSchema.extend({
-  timeBucket: z.string().describe('Time bucket identifier in YYYY-MM-DD format').meta({ example: '2024-01-01' }),
+  timeBucket: z
+    .string()
+    .describe('Time bucket identifier in YYYY-MM-DDT00:00:00.000Z format')
+    .meta({ example: '2024-01-01T00:00:00.000Z' }),
 }).meta({ id: 'TimeBucketAssetDto' });
 
 const stackTupleSchema = z.array(z.string()).length(2).nullable();