Docs: invitation and test email limits, repository-limited token lists and notifications in the API reference (#105)
#100 documented these on the Invitations, Notifications, Tokens and Limits pages; the API reference still had no word of the 429s, the notifications 403 or the narrowed repository lists. Claude-Session: https://claude.ai/code/session_016q5wwBFck8JHq14gHUM2CL Co-authored-by: Claude <noreply@anthropic.com>
Canberk Demirci authored · GitHub committed signed1 parent 6e0e611commit c4e3420a4e716fd9dd311bd073fc0c98de1046ddBrowse files
1 file changed+6−6
modifiedapps/diffinery/src/docs/api-meta.ts+6−6View file
| @@ -139,7 +139,7 @@ | ||
| 139 | 139 | "GET /orgs/{org}/members": { summary: "List organization members", description: "Members only (or site admins). Each entry carries the member's `role`.", access: "account" }, |
| 140 | 140 | "POST /orgs/{org}/invitations": { |
| 141 | 141 | summary: "Invite someone to an organization", |
| 142 | - description: "Emails an invite link. The response holds the link too, so you can share it yourself. Refused with 422 when the address already has a pending invitation to the organization (letter case doesn't matter) or belongs to a member.", | |
| 142 | + description: "Emails an invite link. The response holds the link too, so you can share it yourself. Refused with 422 when the address already has a pending invitation to the organization (letter case doesn't matter) or belongs to a member. You can send at most 50 invitations in 24 hours (site admins aren't limited); more answer 429 `you can send at most 50 invitations in 24 hours; try again later`.", | |
| 143 | 143 | access: "org-admin", |
| 144 | 144 | status: 201, |
| 145 | 145 | body: { email: ["string", "Email address to invite.", true], role: ["string", "`member` (default), `admin` or `owner`."] }, |
| @@ -202,7 +202,7 @@ | ||
| 202 | 202 | }, |
| 203 | 203 | |
| 204 | 204 | // ------------------------------------------------------------ repositories |
| 205 | - "GET /user/repos": { summary: "List repositories you can access", access: "account" }, | |
| 205 | + "GET /user/repos": { summary: "List repositories you can access", description: "A token limited to repositories lists only those repositories.", access: "account" }, | |
| 206 | 206 | "POST /user/repos": { |
| 207 | 207 | summary: "Create a repository for yourself", |
| 208 | 208 | description: "An agent's repositories belong to its owner.", |
| @@ -215,8 +215,8 @@ | ||
| 215 | 215 | default_branch: ["string", "Default branch name (default `main`)."], |
| 216 | 216 | }, |
| 217 | 217 | }, |
| 218 | - "GET /users/{login}/repos": { summary: "List an account's repositories", description: "Only the ones you can see.", access: "account" }, | |
| 219 | - "GET /orgs/{org}/repos": { summary: "List an organization's repositories", description: "Only the ones you can see.", access: "account" }, | |
| 218 | + "GET /users/{login}/repos": { summary: "List an account's repositories", description: "Only the ones you can see. A token limited to repositories lists only those repositories.", access: "account" }, | |
| 219 | + "GET /orgs/{org}/repos": { summary: "List an organization's repositories", description: "Only the ones you can see. A token limited to repositories lists only those repositories.", access: "account" }, | |
| 220 | 220 | "POST /orgs/{org}/repos": { |
| 221 | 221 | summary: "Create an organization repository", |
| 222 | 222 | access: "account", |
| @@ -1333,7 +1333,7 @@ | ||
| 1333 | 1333 | "DELETE /repos/{owner}/{repo}/hooks/{id}": { summary: "Delete a webhook", description: "Audited as `repo.webhook.delete`.", access: "admin", status: 204 }, |
| 1334 | 1334 | |
| 1335 | 1335 | // ------------------------------------------------------------ notifications and email |
| 1336 | - "GET /notifications": { summary: "List notifications", access: "account", query: { all: ["boolean", "`true` to include read ones."] } }, | |
| 1336 | + "GET /notifications": { summary: "List notifications", description: "A token limited to repositories answers 403 `this token is limited to repositories and can't read notifications`, since notifications cover every repository.", access: "account", query: { all: ["boolean", "`true` to include read ones."] } }, | |
| 1337 | 1337 | "PUT /notifications": { summary: "Mark all notifications as read", access: "account", status: 205 }, |
| 1338 | 1338 | "GET /repos/{owner}/{repo}/subscription": { summary: "Get your watch setting", description: "404 when you only get participating notifications (the default), as on GitHub.", access: "read" }, |
| 1339 | 1339 | "PUT /repos/{owner}/{repo}/subscription": { |
| @@ -1349,7 +1349,7 @@ | ||
| 1349 | 1349 | access: "account", |
| 1350 | 1350 | query: { kind: ["string", "Only this kind of email."], since: ["string", "ISO timestamp."], per_page: ["integer", "At most this many (default 50)."], all: ["string", "`1` for everyone's (site admins)."] }, |
| 1351 | 1351 | }, |
| 1352 | - "POST /diffinery/emails/test": { summary: "Send yourself a test email", access: "account" }, | |
| 1352 | + "POST /diffinery/emails/test": { summary: "Send yourself a test email", description: "At most 5 an hour; more answer 429 `you can send at most 5 test emails an hour; try again later`.", access: "account" }, | |
| 1353 | 1353 | "GET /diffinery/admin/email": { summary: "Email delivery status", description: "Whether sending is configured, and counts for the last 24 hours.", access: "site-admin" }, |
| 1354 | 1354 | "GET /diffinery/admin/scheduler": { |
| 1355 | 1355 | summary: "Workflow scheduler state", |