Organizations
Org-level metadata and membership graph. Org creation is web-only
in v1 (the /orgs/new form); the REST surface is read-side until
the CLI gains an org-create flow.
Org shape
{
"id": 42,
"slug": "acme",
"login": "acme",
"display_name": "Acme",
"description": "Acme org",
"location": "",
"website": "",
"plan": "free",
"allow_member_repo_create": true,
"created_at": "2026-05-12T05:00:00Z"
}
login is a gh-compatible alias for slug.
List the authenticated user's orgs
GET /api/v1/user/orgs
Required scope: user:read. Returns the caller's full membership
list (with role) sorted by org slug.
[
{
"org_id": 42,
"slug": "acme",
"login": "acme",
"display_name": "Acme",
"role": "owner"
}
]
List a user's orgs
GET /api/v1/users/{username}/orgs
Required scope: user:read. shithub does not yet distinguish
public/private membership, so this endpoint returns the same set
the named user sees on their own /user/orgs. 404 for unknown
usernames.
Get a single org
GET /api/v1/orgs/{org}
Required scope: user:read. 404 for unknown slugs and
soft-deleted orgs.
List org members
GET /api/v1/orgs/{org}/members
Required scope: user:read. Sorted by role (owner first) then
username.
[
{
"user_id": 7,
"username": "alice",
"display_name": "Alice",
"role": "owner",
"joined_at": "2026-05-12T05:00:00Z"
}
]
Not yet shipped
- Teams REST surface.
- Invitations (accept / decline / cancel).
- Org-level settings and billing plan transitions.
- Member role changes through the API.
View source
| 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. |