@@ -0,0 +1,93 @@ |
| 1 | +# Organizations |
| 2 | + |
| 3 | +Org-level metadata and membership graph. Org creation is web-only |
| 4 | +in v1 (the `/orgs/new` form); the REST surface is read-side until |
| 5 | +the CLI gains an org-create flow. |
| 6 | + |
| 7 | +## Org shape |
| 8 | + |
| 9 | +```json |
| 10 | +{ |
| 11 | + "id": 42, |
| 12 | + "slug": "acme", |
| 13 | + "login": "acme", |
| 14 | + "display_name": "Acme", |
| 15 | + "description": "Acme org", |
| 16 | + "location": "", |
| 17 | + "website": "", |
| 18 | + "plan": "free", |
| 19 | + "allow_member_repo_create": true, |
| 20 | + "created_at": "2026-05-12T05:00:00Z" |
| 21 | +} |
| 22 | +``` |
| 23 | + |
| 24 | +`login` is a gh-compatible alias for `slug`. |
| 25 | + |
| 26 | +## List the authenticated user's orgs |
| 27 | + |
| 28 | +``` |
| 29 | +GET /api/v1/user/orgs |
| 30 | +``` |
| 31 | + |
| 32 | +Required scope: `user:read`. Returns the caller's full membership |
| 33 | +list (with role) sorted by org slug. |
| 34 | + |
| 35 | +```json |
| 36 | +[ |
| 37 | + { |
| 38 | + "org_id": 42, |
| 39 | + "slug": "acme", |
| 40 | + "login": "acme", |
| 41 | + "display_name": "Acme", |
| 42 | + "role": "owner" |
| 43 | + } |
| 44 | +] |
| 45 | +``` |
| 46 | + |
| 47 | +## List a user's orgs |
| 48 | + |
| 49 | +``` |
| 50 | +GET /api/v1/users/{username}/orgs |
| 51 | +``` |
| 52 | + |
| 53 | +Required scope: `user:read`. shithub does not yet distinguish |
| 54 | +public/private membership, so this endpoint returns the same set |
| 55 | +the named user sees on their own `/user/orgs`. `404` for unknown |
| 56 | +usernames. |
| 57 | + |
| 58 | +## Get a single org |
| 59 | + |
| 60 | +``` |
| 61 | +GET /api/v1/orgs/{org} |
| 62 | +``` |
| 63 | + |
| 64 | +Required scope: `user:read`. `404` for unknown slugs and |
| 65 | +soft-deleted orgs. |
| 66 | + |
| 67 | +## List org members |
| 68 | + |
| 69 | +``` |
| 70 | +GET /api/v1/orgs/{org}/members |
| 71 | +``` |
| 72 | + |
| 73 | +Required scope: `user:read`. Sorted by role (owner first) then |
| 74 | +username. |
| 75 | + |
| 76 | +```json |
| 77 | +[ |
| 78 | + { |
| 79 | + "user_id": 7, |
| 80 | + "username": "alice", |
| 81 | + "display_name": "Alice", |
| 82 | + "role": "owner", |
| 83 | + "joined_at": "2026-05-12T05:00:00Z" |
| 84 | + } |
| 85 | +] |
| 86 | +``` |
| 87 | + |
| 88 | +## Not yet shipped |
| 89 | + |
| 90 | +- Teams REST surface. |
| 91 | +- Invitations (accept / decline / cancel). |
| 92 | +- Org-level settings and billing plan transitions. |
| 93 | +- Member role changes through the API. |