Present flat routes as canonical across all API documentation

[jeremy]

Summary

• Update 42 section files to present flat routes (without /buckets/{id} prefix) as the canonical form for API endpoints
• Add a "Flat routes" section to README.md explaining the new URL structure
• Add a "Legacy project-scoped routes" section at the bottom of each migrated section file, listing the old bucket-scoped paths with links to canonical headings
• Update endpoint descriptions, cURL examples, and HTML comment markers throughout
• Regenerate JSON response bodies to reflect flat URLs for subscriptions, comments, completions, and other recording-scoped resources

Intentionally project-scoped (no flat routes)

A few resources remain bucket/project-scoped because no flat routes exist:

• message_types and tools — inherently project-level (categories and dock tools belong to a project)
• webhooks index/create — require bucket context; individual webhook ops (get/update/delete) are flat
• client_approvals and client_correspondences listing — require bucket context; individual access is flat
• timesheets create entry — requires recording+bucket context
• chatbots create line — authenticates via chatbot key, not OAuth; requires bucket prefix

Note on attachments.md

attachments.md was not regenerated because ActiveStorage fixture files were unavailable in the worktree. Attachment responses don't contain any of the URLs affected by flat route migration (no subscription_url, comments_url, etc.), so the file is unaffected.

Test plan

• Verify no bucket-scoped paths remain in endpoint descriptions (only in Legacy sections, intentionally project-scoped files, and JSON bodies)
• Verify every migrated section file has a "Legacy project-scoped routes" section (32 files; 9 without are legitimately non-bucket or intentionally project-scoped)
• Verify README flat routes section is accurate
• Spot-check cURL examples use flat URLs in all migrated sections

[Copilot]

Pull request overview

This PR transitions the Basecamp 4 API documentation to present flat routes (without /buckets/{id} prefix) as the canonical form for all endpoints. The legacy project-scoped routes are preserved for backward compatibility but moved to dedicated sections at the end of each file.

Changes:

• Added documentation for flat routes concept and usage patterns in README.md
• Updated all endpoint descriptions, cURL examples, and HTML comment markers across 34 section files to use flat routes
• Added "Legacy project-scoped routes" sections to each modified file with links to canonical endpoints

Reviewed changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
README.md	Added flat routes section explaining the new canonical URL structure and updated key concept examples
sections/webhooks.md	Updated all endpoints to flat routes, added legacy section
sections/vaults.md	Updated all endpoints to flat routes, added legacy section
sections/uploads.md	Updated all endpoints to flat routes, added legacy section
sections/tools.md	Updated all endpoints to flat routes, added legacy section
sections/todosets.md	Updated all endpoints to flat routes, added legacy section
sections/todos.md	Updated all endpoints to flat routes, added legacy section
sections/todolists.md	Updated all endpoints to flat routes, added legacy section
sections/todolist_groups.md	Updated all endpoints to flat routes, added legacy section
sections/subscriptions.md	Updated all endpoints to flat routes, added legacy section
sections/schedules.md	Updated all endpoints to flat routes, added legacy section
sections/schedule_entries.md	Updated all endpoints to flat routes, added legacy section
sections/recordings.md	Updated all endpoints to flat routes, added legacy section
sections/questions.md	Updated all endpoints to flat routes, added legacy section
sections/questionnaires.md	Updated all endpoints to flat routes, added legacy section
sections/question_answers.md	Updated all endpoints to flat routes, added legacy section
sections/messages.md	Updated all endpoints to flat routes, added legacy section
sections/message_types.md	Updated all endpoints to flat routes, added legacy section
sections/message_boards.md	Updated all endpoints to flat routes, added legacy section
sections/inboxes.md	Updated all endpoints to flat routes, added legacy section
sections/inbox_replies.md	Updated all endpoints to flat routes, added legacy section
sections/forwards.md	Updated all endpoints to flat routes, added legacy section
sections/events.md	Updated all endpoints to flat routes, added legacy section
sections/documents.md	Updated all endpoints to flat routes, added legacy section
sections/comments.md	Updated all endpoints to flat routes, added legacy section
sections/client_visibility.md	Updated all endpoints to flat routes, added legacy section
sections/client_replies.md	Updated all endpoints to flat routes, added legacy section
sections/client_correspondences.md	Updated all endpoints to flat routes, added legacy section
sections/client_approvals.md	Updated all endpoints to flat routes, added legacy section
sections/chatbots.md	Updated all endpoints to flat routes, added legacy section
sections/card_tables.md	Updated all endpoints to flat routes, added legacy section
sections/card_table_steps.md	Updated all endpoints to flat routes, added legacy section
sections/card_table_columns.md	Updated all endpoints to flat routes, added legacy section
sections/card_table_cards.md	Updated all endpoints to flat routes, added legacy section
sections/campfires.md	Updated all endpoints to flat routes, added legacy section

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cd5ac846e1

ℹ️ 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".

[rvanbaalen]

Great improvement! Are there any considerable performance differences between the old and the new URL structure or is this purely 'cosmetic'?

Also, thanks for keeping the old endpoints alive. Now we can upgrade the Ganttify integration to the new URL structure on our own pace.

[jeremy]

Great improvement! Are there any considerable performance differences between the old and the new URL structure or is this purely 'cosmetic'?

No performance difference.

Also, thanks for keeping the old endpoints alive. Now we can upgrade the Ganttify integration to the new URL structure on our own pace.

Note this isn't live yet. I'm assessing whether we can swing it with 100% compatibility. The old URLs will be supported until the end of the Internet.

[rvanbaalen]

I know. I just always stay on top of potential API changes of our integrations 😁

Glad to hear you guys take backwards compatibility serious! 🙏

[alexbudin]

@jeremy thank you for doing all this!