Add Folders API documentation#420
Conversation
Documents the per-user folders API under /my/stacks: listing a person's folders in home-screen order, reading a folder with its grouped projects, and creating, renaming, and deleting folders.
There was a problem hiding this comment.
Pull request overview
Adds public API documentation for My folders (per-user project groupings on the home screen) under /my/stacks, and links it from the main endpoint index.
Changes:
- Add a new
sections/my_folders.mdpage documenting list/show/create/update/delete endpoints for folders (stack(s)on the wire). - Add “My folders” to the README API endpoints index.
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 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| sections/my_folders.md | New documentation page for /my/stacks folder endpoints, parameters, and examples. |
| README.md | Adds “My folders” to the API endpoints list. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (1)
sections/my_folders.md:95
- The endpoint description implies projects are always filed on create ("files the given projects into it"), but
project_idsis documented below as optional and can be omitted/null/empty for an empty folder. Adjust the wording to make the optionality clear so readers don’t assume filing is required.
* `POST /my/stacks.json` creates a new folder for the authenticated user and
files the given [projects][projects] into it. The folder is placed at the top
of the home screen.
jeremy
changed the title
![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: 191e9f4350
ℹ️ 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 2 out of 2 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (1)
sections/folders.md:210
- The PR description says non-JSON
DELETErequests are rejected with406 Not Acceptable, but the DELETE cURL example omits the JSON content type header, which may lead clients to send a non-JSON request.
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE \
| | `name` | String | The folder's name. Defaults to `New folder` when blank or omitted. | | ||
| | `project_ids` | Array<Integer> | IDs of the projects to file into the folder. Each must be a project the user can access, or an all-access project they're eligible to join — filing an all-access project the user isn't yet a member of also grants them access to it. Archived, trashed, or invitation-only projects the user isn't on are rejected: the whole request returns `404 Not Found` and nothing is created. Omit it, or send `null` or an empty array, for an empty folder. | |
Documents folders — the per-user grouping of projects on your home screen — as a public API under
/stacks.Folders are per-user: each person arranges their own home into folders, and filing a project into a folder for yourself doesn't change how anyone else sees it. For historical reasons the path and the wire type say
stack(s)rather thanfolder(s); they're the same thing.Endpoints
GET /stacks.json— your folders, in home-screen orderGET /stacks/:id.json— a folder plus the projects grouped inside itPOST /stacks.json— create a folder, optionally filing projects into itPUT /stacks/:id.json— rename a folderDELETE /stacks/:id.json— delete a folderNotes for API clients
project_idson create is optional — omit it (or sendnull) for an empty folder. Each id must be a project you can access, or an all-access project you're eligible to join; filing an all-access project you aren't yet a member of also adds you to it. Archived, trashed, or invitation-only projects you're not on are rejected, and the whole request fails with404without creating anything.nameonly; a folder's projects, ordering, and image are managed elsewhere.406— and forPOST,PUT, andDELETEthat happens before any change is made.Synced from bc3
doc/api/at646551601fbyscript/api/sync_to_bc3_api— not a hand-edit.