Document joining an all-access project (POST /buckets/:id/admissions.json)

[jeissonneira]

Summary

• Add a Join a project section to sections/people.md documenting POST /buckets/:id/admissions.json — the current person joins a project whose admissions policy allows it (all-access: team or employee)
• Covers the 201 Created empty-body success, the 403 Forbidden / "You must first seek admission" case for invite-only projects and clients on team projects, and why GET /projects.json can't surface a joinable project (it lists only projects you've already joined, so the ID has to come from a URL, a dashboard, or an admin)
• Distinguishes it from Update who can access a project, which grants or revokes other people
• Adds the endpoint to the section's anchor list. Docs only — no API behavior changed

Notes for maintainers

I ran into this building an agent against the API. The projects it needed were all-access, so it should have been able to reach them — but GET /projects.json returns only projects you've already joined, so those projects were simply invisible to it, and nothing in the docs says how to join one. The fix was manual every time: either I joined the project on the agent's behalf, or someone drove the web UI to do it.

POST /buckets/:id/admissions.json does exactly this, and it's been working well for us — the agent now admits itself to an all-access project instead of waiting on a person. Right now the docs cover admissions only as a policy you set on a project (Update a project), never as something a person can act on, so this fills in the other half.

The wording is a proposal — reshape it however fits. One process note: I don't have bc3 access, so this is a hand-edit against the mirror rather than script/api/sync_to_bc3_api output. Happy for it to be treated as a content proposal for doc/api/ and overwritten by the next sync.

[Copilot]

Pull request overview

Documents how users can join eligible all-access projects through the admissions endpoint.

Changes:

• Adds the endpoint to the people API index.
• Documents success, authorization failures, discovery limitations, and cURL usage.

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.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jeissonneira]

@jeremy — mind taking a look when you get a chance? Similar situation to the doors one you merged in #409: an endpoint I ended up relying on for an integration that isn't documented yet.

Happy to reword any of it, or to have it land in bc3's doc/api/ first if you'd rather it come through the sync.