docs(tasks): document optional timezone on task create/update (chat#1881 3c)

[sweetmantech]

What

Documents the optional IANA timezone field on the task contract — the docs side of chat#1881 item 3c, leading the api implementation (api#780) per docs-first.

Added timezone (optional, string, example America/New_York) to CreateTaskRequest and UpdateTaskRequest in api-reference/openapi/releases.json. The cron is interpreted in this zone by the Trigger.dev schedule (DST-aware); defaults to UTC; not stored on scheduled_actions (the Trigger.dev schedule is the source of truth — see the 3c decision on the tracker). Additive diff (+10), required unchanged (optional), JSON re-validated.

Sequencing

Merge order: this → api#780 (contract leads). Tracking: chat#1881 item 3c·docs.

---

Summary by cubic

Documented an optional IANA timezone on task create/update so cron runs in a specified zone. DST-aware, defaults to UTC, applied via the Trigger.dev schedule (not stored separately). Aligns with chat#1881 (item 3c).

• New Features
  • Added timezone (optional string, e.g. "America/New_York") to CreateTaskRequest and UpdateTaskRequest in api-reference/openapi/releases.json; for CreateTaskRequest, defined explicit default: "UTC".
  • Update behavior: sending only timezone re-syncs the Trigger.dev schedule; cron-only updates preserve the existing timezone.

^{Written for commit 6fd8e6f. Summary will update on new commits.}

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[coderabbitai]

Warning

Review limit reached

@sweetmantech, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 33 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f8dd6bd4-85ab-4a91-802c-eb0b2401518c

📥 Commits

Reviewing files that changed from the base of the PR and between 3b28d38 and 6fd8e6f.

📒 Files selected for processing (1)

• api-reference/openapi/releases.json

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/tasks-timezone-field

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cubic-dev-ai]

1 issue found across 1 file

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="api-reference/openapi/releases.json">

<violation number="1" location="api-reference/openapi/releases.json:3061">
P3: Missing `minLength: 1` on `timezone` in UpdateTaskRequest. Every other updatable string field in this schema (title, prompt, schedule, model) enforces `minLength: 1` to reject empty-string updates. Add it for consistency — an empty IANA timezone string would be invalid anyway.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: Missing minLength: 1 on timezone in UpdateTaskRequest. Every other updatable string field in this schema (title, prompt, schedule, model) enforces minLength: 1 to reject empty-string updates. Add it for consistency — an empty IANA timezone string would be invalid anyway.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/releases.json, line 3061:

<comment>Missing `minLength: 1` on `timezone` in UpdateTaskRequest. Every other updatable string field in this schema (title, prompt, schedule, model) enforces `minLength: 1` to reject empty-string updates. Add it for consistency — an empty IANA timezone string would be invalid anyway.</comment>

<file context>
@@ -3058,6 +3058,11 @@
             "description": "Cron expression defining when the task runs (e.g., '0 9 * * 4' for Thursdays at 9 AM)",
             "example": "0 9 * * 4"
           },
+          "timezone": {
+            "type": "string",
+            "description": "Optional IANA time zone (e.g. America/New_York) the cron schedule is interpreted in, DST-aware. Defaults to UTC. Applied to the Trigger.dev schedule (the source of truth); not stored separately.",
</file context>

Suggested change

	"timezone": {
	"type": "string",
	"description": "Optional IANA time zone (e.g. America/New_York) the cron schedule is interpreted in, DST-aware. Defaults to UTC. Applied to the Trigger.dev schedule (the source of truth); not stored separately.",
	"example": "America/New_York"
	},
	"timezone": {
	"type": "string",
	"minLength": 1,
	"description": "Optional IANA time zone the cron is interpreted in (DST-aware). If sent, updates the Trigger.dev schedule; a timezone-only change re-syncs the schedule. A cron-only update preserves the existing time zone.",
	"example": "America/New_York"
	}