Drafts API and My Tasks: new section and draft lifecycle docs#422
Drafts API and My Tasks: new section and draft lifecycle docs#422jeremy wants to merge 1 commit into
Conversation
There was a problem hiding this comment.
Pull request overview
Expands the Basecamp API documentation around draftable content and “My Tasks” (Up Next), adding a new Drafts section and clarifying draft/publish lifecycle semantics for messages/documents plus assignment actions/prioritization.
Changes:
- Add a new Drafts section documenting
GET /my/drafts.jsonand its response semantics. - Document draft creation/publishing behavior for Messages and Documents (including differences in update semantics when publishing drafts).
- Add Act on assignments and Prioritize assignments guidance to My assignments, and note schedule-entry draft behavior.
Tip
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| sections/drafts.md | New Drafts documentation including the GET /my/drafts.json endpoint and example response. |
| sections/messages.md | Clarifies message draft default behavior and adds “Publishing a draft” details. |
| sections/documents.md | Clarifies document draft default behavior and adds “Publishing a draft” details (replace vs merge semantics). |
| sections/my_assignments.md | Adds guidance for acting on assignments and managing Up Next priorities, including validation responses. |
| sections/schedule_entries.md | Documents status behavior on create and clarifies schedule-entry drafts are excluded from “Get my drafts”. |
| README.md | Adds the Drafts section to the endpoint index. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3d13ea2a0e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 42f57ddc64
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (2)
sections/my_assignments.md:653
- This sentence uses “card-table step” (hyphenated) but earlier in the same doc the term is written as “card table steps”. Keep the term consistent throughout this section.
**Note:** these updates replace omitted fields. A to-do update and a card-table step update both clear any field you don't send — including `assignee_ids`, `due_on`, and (for steps) `title` — so resend the current values you want to keep. A card update is the one that preserves omitted `title` and `content`, but even there `due_on` is cleared unless you resend it. In short: to change only assignees or only the due date, echo the record's other current fields in the same request.
sections/my_assignments.md:661
- Minor terminology consistency: use “card table step” (no hyphen) to match earlier mentions of “card table steps” in this doc.
Identify the item by the **recording id** of the thing that carries the priority, not by the assignment id. For a plain to-do or card that's the item's `id`. For a card-table step shown normalized under its parent card, the item's `id` is the *card's* — use the item's `priority_recording_id` from [Get assignments](#get-assignments) instead, which points at the prioritized step.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 349705c0a4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 182f1b8e15
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Mirrors doc/api/ from bc3: the new Drafts section (GET /my/drafts.json), draft/publish lifecycle notes for messages and documents, the My Tasks (Up Next) assignment and prioritization docs, and the card/step update clear-on-omit corrections. Synced from bc3 doc/api/ by script/api/sync_to_bc3_api — not a hand-edit.
This adds a new Drafts endpoint to the API, and documents previously-undocumented behavior around drafting and publishing, and around your My Tasks ("Up Next") list.
New endpoint
GET /my/drafts.jsonreturns a paginated list of your unpublished drafts across every draftable type (messages, documents, uploads, and client approvals/correspondences), most recently updated first.Draft lifecycle for messages and documents
Messages and Documents now spell out how drafting and publishing actually work. This is existing behavior, written down for the first time:
statuson a JSON create leaves the record as a draft. It isn't posted and notifies no one. Sendstatus: "active"to publish immediately.status: "active". A message update merges, so you can publish without resendingcontent. A document update replaces, so you must resendtitleandcontent— a status-only update is rejected.My Tasks
My assignments gains two sections, documenting existing endpoints:
due_onbut leaves other omitted fields unchanged, whereas a step update replaces the step, clearing any oftitle,due_on, orassignee_idsyou omit.Corrections
parent.app_urlfor a client board now renders as the singleton…/client/boardrather than…/client/board.<id>. The examples are corrected to match.active, and a drafted entry is not listed by Get my drafts.Synced from bc3
doc/api/byscript/api/sync_to_bc3_api— not a hand-edit.