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 4 commits 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".
| - [Act on assignments](#act-on-assignments) | ||
| - [Prioritize an assignment](#prioritize-an-assignment) | ||
| - [Deprioritize an assignment](#deprioritize-an-assignment) | ||
| - [Reorder Up Next](#reorder-up-next) |
|
|
||
| A message update **merges** the fields you send, so you don't need to resend `subject` or `content` — the draft's existing content is preserved. | ||
|
|
||
| Publishing is what actually posts the message, and it happens exactly once. It records a single publication event; once the resulting `Event::RelayJob` runs, each subscriber who should hear about the message receives exactly one notification. Creating or re-saving a draft notifies no one — only publishing does. (Documents publish the same way; see [Publishing a draft](documents.md#publishing-a-draft) in the documents section.) |
|
|
||
| * `GET /my/drafts.json` will return a [paginated list][pagination] of the current user's drafts, most recently updated first, regardless of how they were created. Drafts whose project has been archived or trashed are excluded. | ||
|
|
||
| Five kinds of draft are returned: |
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".
| - [Get assignments](#get-assignments) | ||
| - [Get completed assignments](#get-completed-assignments) | ||
| - [Get due assignments](#get-due-assignments) | ||
| - [Act on assignments](#act-on-assignments) |
There was a problem hiding this comment.
In this context, adding Act on assignments to the Endpoints: list makes it look like a callable /my/assignments endpoint, but the linked section is only guidance and has no route bullet like * \METHOD /path`` or request/cURL block. API readers scanning the endpoint list will hit a section that cannot be called directly; please move this overview out of the endpoint list or fold it into a real endpoint section.
AGENTS.md reference: AGENTS.md:L38-L42
Useful? React with 👍 / 👎.
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:
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.