shithub Public

Watch 1 Fork 0 Star 0
markdown · 2215 bytes Raw Blame History

Users

Get the authenticated user

GET /api/v1/user

Required scope: user:read.

Returns the user record for the account that owns the authenticating PAT.

Response

{
  "id": 42,
  "username": "alice",
  "name": "Alice Example",
  "email_verified": true,
  "created_at": "2026-05-09T16:30:00Z"
}
Field Type Notes
id int64 Stable numeric ID.
username string Account username; URL-safe slug.
name string Display name; may be empty if not set.
email_verified bool Whether the primary email has been verified.
created_at string RFC 3339 UTC timestamp of account creation.

Errors

Status When
401 PAT missing/invalid/expired/revoked.
403 PAT lacks user:read scope.
404 User record not found (suspended or deleted between auth and lookup).

Get a user by username

Planned. GET /api/v1/users/{username} is not shipped yet.

Update the authenticated user

Planned. PATCH /api/v1/user is not shipped yet.

List the authenticated user's repos

Planned. GET /api/v1/user/repos is not shipped yet.

Stars

The starred-repos surface for the authenticating user.

List starred repos

GET /api/v1/user/starred

Required scope: user:read.

Returns the list of (owner, repo) pairs the user has starred, most-recent first. Pagination via ?cursor=… and ?per_page=.

Star a repo

PUT /api/v1/user/starred/{owner}/{repo}

Required scope: user (write).

Idempotent: starring an already-starred repo returns 204 and does not duplicate the row. Returns 404 if the repo doesn't exist or the user can't see it.

Unstar a repo

DELETE /api/v1/user/starred/{owner}/{repo}

Required scope: user (write).

Idempotent: unstarring a not-starred repo returns 204.

View source
1 # Users
2
3 ## Get the authenticated user
4
5 ```
6 GET /api/v1/user
7 ```
8
9 Required scope: `user:read`.
10
11 Returns the user record for the account that owns the
12 authenticating PAT.
13
14 ### Response
15
16 ```json
17 {
18 "id": 42,
19 "username": "alice",
20 "name": "Alice Example",
21 "email_verified": true,
22 "created_at": "2026-05-09T16:30:00Z"
23 }
24 ```
25
26 | Field | Type | Notes |
27 |------------------|---------|------------------------------------------------------|
28 | `id` | int64 | Stable numeric ID. |
29 | `username` | string | Account username; URL-safe slug. |
30 | `name` | string | Display name; may be empty if not set. |
31 | `email_verified` | bool | Whether the primary email has been verified. |
32 | `created_at` | string | RFC 3339 UTC timestamp of account creation. |
33
34 ### Errors
35
36 | Status | When |
37 |-------:|-------------------------------------|
38 | 401 | PAT missing/invalid/expired/revoked. |
39 | 403 | PAT lacks `user:read` scope. |
40 | 404 | User record not found (suspended or deleted between auth and lookup). |
41
42 ## Get a user by username
43
44 > **Planned.** `GET /api/v1/users/{username}` is not shipped yet.
45
46 ## Update the authenticated user
47
48 > **Planned.** `PATCH /api/v1/user` is not shipped yet.
49
50 ## List the authenticated user's repos
51
52 > **Planned.** `GET /api/v1/user/repos` is not shipped yet.
53
54 ## Stars
55
56 The starred-repos surface for the authenticating user.
57
58 ### List starred repos
59
60 ```
61 GET /api/v1/user/starred
62 ```
63
64 Required scope: `user:read`.
65
66 Returns the list of `(owner, repo)` pairs the user has starred,
67 most-recent first. Pagination via `?cursor=…` and `?per_page=`.
68
69 ### Star a repo
70
71 ```
72 PUT /api/v1/user/starred/{owner}/{repo}
73 ```
74
75 Required scope: `user` (write).
76
77 Idempotent: starring an already-starred repo returns `204` and
78 does not duplicate the row. Returns `404` if the repo doesn't
79 exist or the user can't see it.
80
81 ### Unstar a repo
82
83 ```
84 DELETE /api/v1/user/starred/{owner}/{repo}
85 ```
86
87 Required scope: `user` (write).
88
89 Idempotent: unstarring a not-starred repo returns `204`.