Expose scheduled publishing for drafts (`scheduled_posting_at`) as a writable field

[bsmarsh333]

Summary

The web app can schedule a draft message to publish later ("Post later…" in the message editor), and the API already reports the result: GET /my/drafts.json returns scheduled_posting_at, documented in bc-api sections/drafts.md as "null unless the draft is scheduled to publish later", and the OpenAPI spec in this repository carries it as a required, nullable property of the draft object. There is no way to set it. Requesting a write path so integrations can stage a draft and have Basecamp publish it at a chosen time.

What I tried

• PUT /buckets/{bucket_id}/messages/{message_id}.json with {"scheduled_posting_at": "2026-09-07T16:00:00Z"} returns 200 and the message unchanged; the drafts listing still shows null. Wrapping it as {"message": {...}} behaves the same.
• The documented update parameters are subject, content, category_id, subscriptions, and notify; the create parameters add status and visible_to_clients. Neither accepts a posting time.
• The OpenAPI spec has no schedule operation on any message path; the only occurrence of scheduled_posting_at is the read-only draft projection.
• Setting the time through the web editor works and is then visible through GET /my/drafts.json, so the field round-trips fine on the read side.

Why it matters

We generate a weekly company report as a draft from an automation account and want Basecamp itself to publish it at 9:00 AM on Monday. Without a write path we have to keep a separate scheduler alive to call the publish endpoint at that moment, which is fragile compared with letting Basecamp own the timing the way the editor already does.

Proposal

Accept scheduled_posting_at (ISO 8601) on message create and update while status is drafted; publishing at that time would behave exactly as the editor's "Schedule and save". Sending null would clear the schedule. Documenting the account or user timezone rule for the value would help too: in our testing, the editor interprets the picked hour in the posting account's timezone, so two accounts in the same company scheduled "9:00 AM" and landed an hour apart.

Environment

Basecamp 4, account with two API identities (a person and an automation user), calls made through the official CLI and raw PUT requests, September 2026.

[jeremy]

Verdict, checked against bc3 master (56a3e6493b): this is an API gap, not an SDK one, so the SDK cannot expose it yet.

What the server does today:

• scheduled_posting_at is not a recognized parameter on any messages or documents endpoint. MessagesController#message_params permits only subject and content; create and update take the rest from status, category_id, subscriptions, notify and visible_to_clients. A scheduled_posting_at key in the body, top-level or under message, is dropped by strong params, which is the 200-and-unchanged you observed.
• The only emitter is GET /my/drafts.json (app/views/api/my/drafts/index.json.jbuilder). The message and document show payloads do not carry the field, so even once it is writable there is nothing on the resource itself to confirm it against.
• Scheduling is owned by Recording::SchedulablePosting (one ScheduledPosting row per recording, perform_at), validated to drafted recordings only, and fired by an hourly Recording::ScheduledPosting.enqueue_due cron, so a scheduled time publishes up to an hour late by design. Publishing a draft via status: active cancels the schedule.
• On the timezone question: API requests run with Time.zone = "UTC" (ApiRequest#set_utc_timezone), while the web editor parses the picked hour in the posting person's profile time zone. That is the hour of drift between your two accounts.

What bc3 needs, in order:

1. Accept a top-level scheduled_posting_at (ISO 8601 with offset; null clears) on messages and documents create and update, alongside the existing form-shaped scheduling params, in Recording::ScheduledPostingParams. The model already restricts it to drafts.
2. Emit scheduled_posting_at on the message and document show payloads so a write is observable on the resource.
3. Document it in doc/api/sections/messages.md and documents.md (create, update, and the "Publishing a draft" section), including the UTC rule and the hourly granularity.
4. API tests for create, update and clear.

The SDK follows from there: scheduled_posting_at on the CreateMessage/UpdateMessage (and document) inputs and on the Message/Document shapes in spec/basecamp.smithy, regenerated into all six SDKs, plus the CLI flag. The bc3 change is in flight now (no PR number yet); this issue stays open and the SDK operation follows once it merges.

[bsmarsh333]

@jeremy Thank you. That is a clearer answer than I expected, and the UTC versus profile-zone detail explains exactly what we saw. We will aim schedules early given the hourly sweep.

One process question, since we are likely to hit more of these as we automate against the API: when we can tell an issue is on the API side rather than the SDK, is there a better place to report it? bc-api has issues turned off, so this repo was the only door we could find. If filing here is fine even for pure API gaps, we will keep doing that.

[jeremy]

@bsmarsh333 here is good!