Document create-time visible_to_clients on content creates#414
Conversation
The create endpoints for messages, documents, to-do lists, questions, uploads, cloud files, Google documents, and schedule entries already accept a visible_to_clients flag, letting you post a recording and set its client visibility in a single request instead of following up with a client_visibility update. Document it consistently across those sections: - It's always a top-level field. For the sections whose body nests fields under a wrapper object (questions, cloud_files, google_documents), the flag must be a sibling of that object, not inside it. - It defaults to false for team members creating directly under the tool; a client always creates client-visible records. - For vault-based tools (documents, uploads, cloud files, Google documents), it applies only when creating directly in the tool's vault — items created inside a folder inherit the folder's visibility. Also note in the Client visibility section that individual cards inherit their card table's visibility, alongside the existing to-do note.
![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: 5bc6e9dc0d
ℹ️ 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
This PR updates the Basecamp API documentation to consistently describe the visible_to_clients flag on several “create” endpoints, clarifying where the flag belongs in request bodies, what it defaults to, and (for vault-based tools) when it applies.
Changes:
- Documented
visible_to_clientsas an optional create-time parameter across multiple resources (messages, documents, uploads, cloud files, Google documents, questions, schedule entries, to-do lists). - Clarified that for wrapper-bodied creates (e.g., questions / cloud files / Google documents),
visible_to_clientsis a top-level field (sibling of the wrapper object). - Updated the Client visibility section to note cards inherit their card table’s visibility (alongside the existing to-do inheritance note).
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 9 out of 9 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| sections/uploads.md | Adds visible_to_clients to the upload create endpoint docs and links to Client visibility. |
| sections/todolists.md | Adds visible_to_clients to the to-do list create endpoint optional parameters and links to Client visibility. |
| sections/schedule_entries.md | Adds visible_to_clients to schedule entry create optional parameters and links to Client visibility. |
| sections/questions.md | Documents visible_to_clients as top-level for question creates and updates the example payload/cURL. |
| sections/messages.md | Adds visible_to_clients to message create optional parameters and links to Client visibility. |
| sections/google_documents.md | Clarifies visible_to_clients is top-level (sibling of google_document) and notes vault/folder behavior. |
| sections/documents.md | Adds visible_to_clients to document create optional parameters and links to Client visibility. |
| sections/cloud_files.md | Clarifies visible_to_clients is top-level (sibling of cloud_file) and notes vault/folder behavior. |
| sections/client_visibility.md | Adds an inheritance note for individual cards (card table visibility). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The create endpoints for messages, documents, to-do lists, questions, uploads, cloud files, Google documents, and schedule entries already accept a
visible_to_clientsflag, letting you post a recording and set its client visibility in a single request instead of following up with a client visibility update. This documents that flag consistently across those create sections.What the docs now say
questions,cloud_files,google_documents), the flag must be a sibling of that object, not inside it.falsefor team members creating directly under the tool; a client always creates client-visible records.Also notes in the Client visibility section that individual cards inherit their card table's visibility, alongside the existing to-do note.
Recordings that inherit their visibility (individual to-dos and cards) can't be toggled individually —
PUT .../client_visibilityreturns403for them — so their create sections intentionally don't document the flag.