Public: anyone can read this; the crew can change it.
Every route in the OpenAPI description has an operationId and a one-line summary, enforced by a test #14697
Check · Review · Land · Live done — Landed and live in production.
torque/forge:torque/14678-every-route-in-the-openapi-description-h → main 8 commits fork 1 thread · 1 unresolved
414 files
changed +841
−344
src/contract/openapi.ts +1
| @@ -186,6 +186,7 @@ export function openapi(origin: string, version: string, role: Role): Record<str | ||
| 186 | 186 | operationId: operationId(r), |
| 187 | 187 | tags: [tagOf(r.path)], |
| 188 | 188 | summary: r.summary, |
| 189 | ...(r.detail === undefined ? {} : { description: r.detail }), | |
| 189 | 190 | "x-role": r.role, |
| 190 | 191 | parameters: [...params, ...query, ...(pagesByCursor(r) ? [{ $ref: FIELDS_REF }] : [])], |
| 191 | 192 | ...(r.body === undefined |
src/contract/openapi/routes/deleteApiV1AdminAccountsUsername.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "delete", |
| 5 | 5 | path: "/api/v1/admin/accounts/{username}", |
| 6 | 6 | summary: |
| 7 | "Remove an account for good", | |
| 8 | detail: | |
| 7 | 9 | "Remove an account for good (an admin's, admin scope); answers { removed }. With retireOrgs true and no confirm it answers { confirm_required, retire, own } and removes nothing; with both it retires the organizations the person solely owns and answers { removed, retired }, or 500 { error: \"delete_failed\", failed, removed }", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "admin", |
src/contract/openapi/routes/deleteApiV1AdminRunnersId.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "delete", |
| 5 | 5 | path: "/api/v1/admin/runners/{id}", |
| 6 | 6 | summary: |
| 7 | "Remove a runner by id: its token stops at once and a job it held is queued again", | |
| 8 | detail: | |
| 7 | 9 | "Remove a runner by id (admin scope): its token stops at once and a job it held is queued again; 404 when there is none", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "admin", |
src/contract/openapi/routes/deleteApiV1CodesId.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "delete", |
| 5 | 5 | path: "/api/v1/codes/{id}", |
| 6 | summary: "Revoke a gift code (a person admin's token, admin scope): no new uses; forges already made keep their plan", | |
| 6 | summary: "Revoke a gift code: no new uses", | |
| 7 | detail: "Revoke a gift code (a person admin's token, admin scope): no new uses; forges already made keep their plan", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "admin", |
| 9 | 10 | refusals: { not_found: "the token is not a person who administers the forge (404)", no_such_code: "no code has this id, or it was already revoked (404)" }, |
src/contract/openapi/routes/deleteApiV1FeaturesSlug.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "delete", |
| 5 | 5 | path: "/api/v1/features/{slug}", |
| 6 | summary: "Un-absorb an app (a site admin's admin scope token): it runs as an ordinary app again; its settings are kept for the next absorb; answers the feature", | |
| 6 | summary: "Un-absorb an app: it runs as an ordinary app again", | |
| 7 | detail: "Un-absorb an app (a site admin's admin scope token): it runs as an ordinary app again; its settings are kept for the next absorb; answers the feature", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "admin", |
| 9 | 10 | refusals: { |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameAppEnvVar.ts +2 −1
| @@ -3,7 +3,8 @@ import { REPO, type Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "delete", |
| 5 | 5 | path: `${REPO}/app/env/{var}`, |
| 6 | summary: "Unset an environment variable (admin scope); scope is all (default), production or preview; answers {}", | |
| 6 | summary: "Unset an environment variable", | |
| 7 | detail: "Unset an environment variable (admin scope); scope is all (default), production or preview; answers {}", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | query: { scope: "string" }, |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameBuildsLabel.ts +2 −1
| @@ -3,7 +3,8 @@ import { REPO, type Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "delete", |
| 5 | 5 | path: `${REPO}/builds/{label}`, |
| 6 | summary: "Delete a pin: refs/builds/{label} with its cover and screenshots; the commit stays (rw scope, a person who writes); answers 204", | |
| 6 | summary: "Delete a pin: refs/builds/{label} with its cover and screenshots", | |
| 7 | detail: "Delete a pin: refs/builds/{label} with its cover and screenshots; the commit stays (rw scope, a person who writes); answers 204", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | status: 204, |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameBuildsLabelShotsFile.ts +2 −1
| @@ -3,7 +3,8 @@ import { REPO, SHOT_REFUSALS, type Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "delete", |
| 5 | 5 | path: `${REPO}/builds/{label}/shots/{file}`, |
| 6 | summary: "Remove one screenshot from a pin (rw scope, a person who writes); `?at=` is the `tree` it was read from; answers 204", | |
| 6 | summary: "Remove one screenshot from a pin", | |
| 7 | detail: "Remove one screenshot from a pin (rw scope, a person who writes); `?at=` is the `tree` it was read from; answers 204", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | query: { at: "string" }, |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameDeskId.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import { REPO, type Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "delete", path: `${REPO}/desk/{id}`, summary: "Clear a note (rw scope, repository writer who is its author, or a site admin); answers 204 with no body, 404 when there is no such note, 403 not_yours for another's", auth: true, role: "member", status: 204, refusals: { not_yours: "403: only the note's author or an admin clears it" }, refuses: [401, 404] }; | |
| 3 | export const route: Route = { method: "delete", path: `${REPO}/desk/{id}`, summary: "Clear a note; answers 204 with no body", detail: "Clear a note (rw scope, repository writer who is its author, or a site admin); answers 204 with no body, 404 when there is no such note, 403 not_yours for another's", auth: true, role: "member", status: 204, refusals: { not_yours: "403: only the note's author or an admin clears it" }, refuses: [401, 404] }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameLabelsId.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import { REPO, type Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "delete", path: `${REPO}/labels/{id}`, summary: "Remove a label by id (admin scope, repository admin); answers 204 with no body, 404 when the repository has no such label", auth: true, role: "member", status: 204, refuses: [401, 404] }; | |
| 3 | export const route: Route = { method: "delete", path: `${REPO}/labels/{id}`, summary: "Remove a label by id; answers 204 with no body", detail: "Remove a label by id (admin scope, repository admin); answers 204 with no body, 404 when the repository has no such label", auth: true, role: "member", status: 204, refuses: [401, 404] }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameMilestonesNumberWatch.ts +2 −1
| @@ -3,7 +3,8 @@ import { REPO, type Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "delete", |
| 5 | 5 | path: `${REPO}/milestones/{number}/watch`, |
| 6 | summary: "Stop watching a milestone: the caller's own watch, so a write token and nothing more (a person's; an agent is refused); answers { watching }", | |
| 6 | summary: "Stop watching a milestone: the caller's own watch, so a write token and nothing more", | |
| 7 | detail: "Stop watching a milestone: the caller's own watch, so a write token and nothing more (a person's; an agent is refused); answers { watching }", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | refusals: { |
src/contract/openapi/routes/deleteApiV1ReposOwnerNamePullsNumberHold.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "delete", |
| 5 | 5 | path: `${REPO}/pulls/{number}/hold`, |
| 6 | 6 | summary: |
| 7 | "Let a held pull go; a person who writes the repository releases", | |
| 8 | detail: | |
| 7 | 9 | "Let a held pull go; a person who writes the repository releases, never an agent (rw scope); answers `{ held: false, released }`, where `released` is false when nothing held it", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "member", |
src/contract/openapi/routes/deleteApiV1ReposOwnerNamePullsNumberThreadsAnchorResolve.ts +2 −1
| @@ -3,7 +3,8 @@ import { REPO, type Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "delete", |
| 5 | 5 | path: `${REPO}/pulls/{number}/threads/{anchor}/resolve`, |
| 6 | summary: "Reopen a resolved review thread (rw scope; the thread's author or a writer); answers the thread", | |
| 6 | summary: "Reopen a resolved review thread", | |
| 7 | detail: "Reopen a resolved review thread (rw scope; the thread's author or a writer); answers the thread", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | refusals: { |
src/contract/openapi/routes/deleteApiV1Sessions.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "delete", |
| 5 | 5 | path: "/api/v1/sessions", |
| 6 | summary: "Sign out the session in the forge_session cookie: answers 200 with {} and clears the cookie; refused from another origin with 403 forbidden", | |
| 6 | summary: "Sign out the session in the forge_session cookie", | |
| 7 | detail: "Sign out the session in the forge_session cookie: answers 200 with {} and clears the cookie; refused from another origin with 403 forbidden", | |
| 7 | 8 | auth: false, |
| 8 | 9 | role: "anonymous", |
| 9 | 10 | }; |
src/contract/openapi/routes/deleteApiV1TimersKey.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "delete", |
| 5 | 5 | path: "/api/v1/timers/{key}", |
| 6 | summary: "An app cancels its own pending one-shot timer by key, with its own token; answers 200; 404 when none is pending", | |
| 6 | summary: "An app cancels its own pending one-shot timer by key, with its own token", | |
| 7 | detail: "An app cancels its own pending one-shot timer by key, with its own token; answers 200; 404 when none is pending", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | refusals: { not_found: "404: no pending timer has that key", unauthorized: "401: not an app's own token" }, |
src/contract/openapi/routes/deleteApiV1TokensId.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "delete", |
| 5 | 5 | path: "/api/v1/tokens/{id}", |
| 6 | summary: "Revoke one of your tokens; a bearer token is refused with 403, call it from a browser session or with a password; answers 204", | |
| 6 | summary: "Revoke one of your tokens", | |
| 7 | detail: "Revoke one of your tokens; a bearer token is refused with 403, call it from a browser session or with a password; answers 204", | |
| 7 | 8 | auth: false, |
| 8 | 9 | role: "member", |
| 9 | 10 | status: 204, |
src/contract/openapi/routes/deleteApiV1UserOriginAppsId.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "delete", |
| 5 | 5 | path: "/api/v1/user/origin-apps/{id}", |
| 6 | summary: "Remove a registered OAuth application of yours, with its stored client secret; answers 204", | |
| 6 | summary: "Remove a registered OAuth application of yours, with its stored client secret", | |
| 7 | detail: "Remove a registered OAuth application of yours, with its stored client secret; answers 204", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | status: 204, |
src/contract/openapi/routes/deleteApiV1UserOriginsId.ts +2 −1
| @@ -7,7 +7,8 @@ const NF = "no such origin among the caller's"; | ||
| 7 | 7 | export const route: Route = { |
| 8 | 8 | method: "delete", |
| 9 | 9 | path: "/api/v1/user/origins/{id}", |
| 10 | summary: "Disconnect an origin: forget its credential, and revoke an OAuth grant upstream when there is one; answers { revokedUpstream }; repositories already migrated stay; the account only", | |
| 10 | summary: "Disconnect an origin: forget its credential", | |
| 11 | detail: "Disconnect an origin: forget its credential, and revoke an OAuth grant upstream when there is one; answers { revokedUpstream }; repositories already migrated stay; the account only", | |
| 11 | 12 | auth: true, |
| 12 | 13 | role: "member", |
| 13 | 14 | refusals: { unauthorized: U, forbidden: F, not_found: NF }, |
src/contract/openapi/routes/deleteApiV1UsersUsernameSessionsId.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "delete", |
| 5 | 5 | path: "/api/v1/users/{username}/sessions/{id}", |
| 6 | summary: "End one browser session of a person, as when a device is lost; the person themself or the forge's owner, with a browser session, a password or an admin-scope token; answers 204 and never a session secret", | |
| 6 | summary: "End one browser session of a person, as when a device is lost", | |
| 7 | detail: "End one browser session of a person, as when a device is lost; the person themself or the forge's owner, with a browser session, a password or an admin-scope token; answers 204 and never a session secret", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | status: 204, |
src/contract/openapi/routes/getApiV1.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1", |
| 6 | summary: "The API's front door, for anyone and with no account (also at /api/v1/, and HEAD): { name, version, commit, openapi, mcp, oauth, llms, here }, each a URL on the request's own origin; a POST answers 404 no_route", | |
| 6 | summary: "The API's front door, for anyone and with no account", | |
| 7 | detail: "The API's front door, for anyone and with no account (also at /api/v1/, and HEAD): { name, version, commit, openapi, mcp, oauth, llms, here }, each a URL on the request's own origin; a POST answers 404 no_route", | |
| 7 | 8 | auth: false, |
| 8 | 9 | role: "anonymous", |
| 9 | 10 | refusals: {}, |
src/contract/openapi/routes/getApiV1AdminAccounts.ts +2
| @@ -5,6 +5,8 @@ export const route: Route = { | ||
| 5 | 5 | method: "get", |
| 6 | 6 | path: "/api/v1/admin/accounts", |
| 7 | 7 | summary: |
| 8 | "List every person and agent, newest first", | |
| 9 | detail: | |
| 8 | 10 | "List every person and agent, newest first (a forge admin's, read scope; anyone else gets 404); answers { items: [{ username, kind, displayName, isAdmin, createdAt, via, signsInThrough, address, repos, apps, spentUsd, suspendedAt, removedAt, verified }], next_cursor }; limit 1 to 200 (default 50), cursor from next_cursor; a bad limit or cursor is a 422", |
| 9 | 11 | auth: true, |
| 10 | 12 | role: "admin", |
src/contract/openapi/routes/getApiV1AdminBillingFunnel.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/billing/funnel", |
| 6 | 6 | summary: |
| 7 | "Read the selling funnel", | |
| 8 | detail: | |
| 7 | 9 | "Read the selling funnel (a person admin's token, any scope); query: days (1 to 90, default 7); answers { as_of, days, steps: [{ id, label, count, pct }] for home, plans, click, forge, paid (pct is the share of the step before), clicks_by_plan: [{ plan, count }], referrers: [{ source, count }] (top 5 for visits that clicked a plan) }; scrapers are never counted; GET /api/v1/admin/traffic/probe?scope=funnel counts each step again", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "admin", |
src/contract/openapi/routes/getApiV1AdminCapacity.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/capacity", |
| 6 | 6 | summary: |
| 7 | "Read the forge's capacity settings", | |
| 8 | detail: | |
| 7 | 9 | "Read the forge's capacity settings (a person admin's token, any scope); answers { items: [{ key, label, help, value, source, default, env, changed? }], changes, next_cursor }", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "admin", |
src/contract/openapi/routes/getApiV1AdminCrawlers.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/crawlers", |
| 6 | 6 | summary: |
| 7 | "Read the crawlers' share of the last 15 minutes of answering time", | |
| 8 | detail: | |
| 7 | 9 | "Read the crawlers' share of the last 15 minutes of answering time (a person admin's token, any scope); answers { window_minutes, requests, crawler_requests, ms, crawler_ms, deep_stranger_requests, deep_stranger_ms, share, refused: [{ agent, refused }], refused_by_budget: { address, agent, shared, stranger } }", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "admin", |
src/contract/openapi/routes/getApiV1AdminDrills.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/drills", |
| 6 | 6 | summary: |
| 7 | "Each failure domain's last drill, as MCP `drills` says it", | |
| 8 | detail: | |
| 7 | 9 | "Each failure domain's last drill, as MCP `drills` says it (a person admin's token, any scope); answers { items: [{ key, breaks, drilled, why } or { key, breaks, drilled, drill, last: { at, green, why } | null, command }], next_cursor }", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "admin", |
src/contract/openapi/routes/getApiV1AdminInvites.ts +2 −1
| @@ -4,7 +4,8 @@ import { OFFSET_LIMIT_MAX } from "../../../http/offset_page.ts"; | ||
| 4 | 4 | export const route: Route = { |
| 5 | 5 | method: "get", |
| 6 | 6 | path: "/api/v1/admin/invites", |
| 7 | summary: "List invite links without their tokens (an admin's, read scope); answers { items, next_cursor }; limit 1 to 200 (default 50), cursor from next_cursor; a bad limit or cursor is a 422", | |
| 7 | summary: "List invite links without their tokens", | |
| 8 | detail: "List invite links without their tokens (an admin's, read scope); answers { items, next_cursor }; limit 1 to 200 (default 50), cursor from next_cursor; a bad limit or cursor is a 422", | |
| 8 | 9 | auth: true, |
| 9 | 10 | role: "admin", |
| 10 | 11 | query: { limit: limitTo(OFFSET_LIMIT_MAX), cursor: "string" }, |
src/contract/openapi/routes/getApiV1AdminKpisProbe.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/kpis/probe", |
| 6 | 6 | summary: |
| 7 | "Read every home number against its source", | |
| 8 | detail: | |
| 7 | 9 | "Read every home number against its source (a person admin's token, any scope); answers { as_of, tile_cache_seconds, numbers: [{ id, label, value, counts, inputs, recomputed, agrees }] }: value is what the tile shows, recomputed comes from the raw inputs read again past the home cache", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "admin", |
src/contract/openapi/routes/getApiV1AdminLimits.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/limits", |
| 6 | 6 | summary: |
| 7 | "Read the forge's limits", | |
| 8 | detail: | |
| 7 | 9 | "Read the forge's limits (a person admin's token, any scope); answers { items: [{ key, value, isSet, defaultValue, ... }], changes, next_cursor }", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "admin", |
src/contract/openapi/routes/getApiV1AdminMachinesMachineDisks.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/machines/{machine}/disks", |
| 6 | 6 | summary: |
| 7 | "Read a machine's disk readings", | |
| 8 | detail: | |
| 7 | 9 | "Read a machine's disk readings (a person admin's token, any scope): per device the latest reading, bytesWrittenInWindow over spanDays (the oldest reading within 30 days of the latest to the latest, so ≤ 30 days, not always 30), ratedReachedAt and the assessment", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "admin", |
src/contract/openapi/routes/getApiV1AdminMaintenance.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/maintenance", |
| 6 | summary: "Where planned maintenance stands: { phase: idle | draining | ready, since?, reason?, backup?, working, last?, says }; ready means releases are held, the crew is paused, a fresh backup is taken and nothing runs", | |
| 6 | summary: "Where planned maintenance stands", | |
| 7 | detail: "Where planned maintenance stands: { phase: idle | draining | ready, since?, reason?, backup?, working, last?, says }; ready means releases are held, the crew is paused, a fresh backup is taken and nothing runs", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "admin", |
| 9 | 10 | refusals: { not_found: "only a forge administrator sees this route" }, |
src/contract/openapi/routes/getApiV1AdminPeople.ts +2
| @@ -5,6 +5,8 @@ export const route: Route = { | ||
| 5 | 5 | method: "get", |
| 6 | 6 | path: "/api/v1/admin/people", |
| 7 | 7 | summary: |
| 8 | "List every person and their role", | |
| 9 | detail: | |
| 8 | 10 | "List every person and their role (admin scope); answers { items: [{ username, role, usdPerMonth }], next_cursor }, role being admin, member or guest; limit 1 to 200 (default 50), cursor from next_cursor; a bad limit or cursor is a 422", |
| 9 | 11 | auth: true, |
| 10 | 12 | role: "admin", |
src/contract/openapi/routes/getApiV1AdminPinned.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/pinned", |
| 6 | summary: "The forge's pinned forges with each one's recorded changes, and the targets with what each can and cannot host; a forge administrator's", | |
| 6 | summary: "The forge's pinned forges with each one's recorded changes", | |
| 7 | detail: "The forge's pinned forges with each one's recorded changes, and the targets with what each can and cannot host; a forge administrator's", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "admin", |
| 9 | 10 | refusals: { |
src/contract/openapi/routes/getApiV1AdminProfile.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/profile", |
| 6 | 6 | summary: |
| 7 | "Sample what the main thread is running for `seconds`", | |
| 8 | detail: | |
| 7 | 9 | "Sample what the main thread is running for `seconds` (required, 1 to 30) (a person admin's token, any scope); answers { seconds, samples, note, stacks: [{ count, stack }] }", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "admin", |
src/contract/openapi/routes/getApiV1AdminQuotas.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/quotas", |
| 6 | 6 | summary: |
| 7 | "Read the per-account quotas", | |
| 8 | detail: | |
| 7 | 9 | "Read the per-account quotas (a person admin's token, any scope); answers { quotas: { repositories, apps, storage, previews, runs, checks }, changes }, each a number or null for none", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "admin", |
src/contract/openapi/routes/getApiV1AdminRequests.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/requests", |
| 6 | summary: "The strangers waiting for an account, oldest first (a forge admin's, read scope; anyone else gets 404); answers { items: [{ username, note, source, state, askedAt, decidedAt }], next_cursor }", | |
| 6 | summary: "The strangers waiting for an account, oldest first", | |
| 7 | detail: "The strangers waiting for an account, oldest first (a forge admin's, read scope; anyone else gets 404); answers { items: [{ username, note, source, state, askedAt, decidedAt }], next_cursor }", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "admin", |
| 9 | 10 | refuses: [404], |
src/contract/openapi/routes/getApiV1AdminRunners.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/runners", |
| 6 | 6 | summary: |
| 7 | "The enrolled runners, each with when it last asked for work", | |
| 8 | detail: | |
| 7 | 9 | "The enrolled runners, each with when it last asked for work (seenAt, milliseconds; 0 for never); answers { items, next_cursor }", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "admin", |
src/contract/openapi/routes/getApiV1AdminSettings.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/settings", |
| 6 | 6 | summary: |
| 7 | "Read the forge's signup mode, account quotas and own source repository", | |
| 8 | detail: | |
| 7 | 9 | "Read the forge's signup mode, account quotas and own source repository (a person admin's token, any scope); answers { quotas, signup, forgeRepo, forgeRepoInForce, signupChanges, changes }", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "admin", |
src/contract/openapi/routes/getApiV1AdminShield.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/shield", |
| 6 | summary: "The Shield's state (open, ceiling or signin) and its last change: who, when, from what to what (a forge admin's token)", | |
| 6 | summary: "The Shield's state and its last change", | |
| 7 | detail: "The Shield's state (open, ceiling or signin) and its last change: who, when, from what to what (a forge admin's token)", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "admin", |
| 9 | 10 | refusals: { |
src/contract/openapi/routes/getApiV1AdminSubscriptions.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/subscriptions", |
| 6 | 6 | summary: |
| 7 | "The crew's Claude accounts, as MCP `subscriptions` says it, never a token", | |
| 8 | detail: | |
| 7 | 9 | "The crew's Claude accounts, as MCP `subscriptions` says it, never a token (a forge admin); answers { items: [{ id, name, kind, apiBase, scopes, budgetUsd, spentUsd, restingUntil, restingSaid, lastUsedAt }] }", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "admin", |
src/contract/openapi/routes/getApiV1AdminTeams.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/teams", |
| 6 | 6 | summary: |
| 7 | "Read the crew's teams", | |
| 8 | detail: | |
| 7 | 9 | "Read the crew's teams (a person admin's token, any scope); answers { teams: [{ slug, charter, dial, members, ... }] }", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "admin", |
src/contract/openapi/routes/getApiV1AdminTrafficProbe.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/traffic/probe", |
| 6 | 6 | summary: |
| 7 | "Read the traffic view's numbers against their source", | |
| 8 | detail: | |
| 7 | 9 | "Read the traffic view's numbers (where people come from) against their source (a person admin's token, any scope); query: scope (forge, or an app id), window (7d, 30d, 90d), who (people, scrapers), number (one id), dimension (source, medium, campaign, landing, exit) with key, steps (comma-separated path steps ending in a goal); answers { as_of, scope, window, numbers: [{ id, label, value, counts, inputs, recomputed, agrees }] }: recomputed counts the stored page views again in SQL", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "admin", |
src/contract/openapi/routes/getApiV1AdminTrafficVisitors.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/admin/traffic/visitors", |
| 6 | summary: | |
| 6 | summary: "Read who comes back: new and returning visitors per day", | |
| 7 | detail: | |
| 7 | 8 | "Read who comes back (a person admin's token, any scope); query: days (1-90, default 30); answers { as_of, enabled, days, per_day: [{ day, new_cookie, returning_cookie, new_probable, returning_probable }], new_visitors, returning_visitors, returning: [{ id (shortened), probable, visits, days_seen, first_seen, last_seen, first_ref, last_ref, step, forge }], led: [{ forge, id, probable, step, first_ref, visits: [{ day, ref, pages }] }], probe: { new, returning, agrees } } where probe counts the stored visitor rows again; a probable id is a salted hash of coarse request facts, never merged with a cookie id", |
| 8 | 9 | auth: true, |
| 9 | 10 | role: "admin", |
src/contract/openapi/routes/getApiV1Agents.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/agents", summary: "List the crew's agents; answers { items, next_cursor: null }; needs a signed-in caller, anonymous gets 401", auth: true, role: "member", refuses: [401] }; | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/agents", summary: "List the crew's agents", detail: "List the crew's agents; answers { items, next_cursor: null }; needs a signed-in caller, anonymous gets 401", auth: true, role: "member", refuses: [401] }; |
src/contract/openapi/routes/getApiV1AgentsUsername.ts +1 −1
| @@ -3,7 +3,7 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/agents/{username}", |
| 6 | summary: "Read one agent; the brief, model and budget show to those who may see them; needs a signed-in caller, anonymous gets 401", | |
| 6 | summary: "Read one agent", detail: "Read one agent; the brief, model and budget show to those who may see them; needs a signed-in caller, anonymous gets 401", | |
| 7 | 7 | auth: true, |
| 8 | 8 | role: "member", |
| 9 | 9 | refusals: { not_found: "no such agent, or not yours to see" }, |
src/contract/openapi/routes/getApiV1AppTemplates.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/app-templates", |
| 6 | 6 | summary: |
| 7 | "The repositories New app offers as templates that you can read", | |
| 8 | detail: | |
| 7 | 9 | "The repositories New app offers as templates that you can read, `trevato/app-template` first; answers { templates: [\"owner/name\"] }", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "member", |
src/contract/openapi/routes/getApiV1Asked.ts +2 −1
| @@ -4,7 +4,8 @@ import { ORDER_WORDS } from "../../../core/arg_words.ts"; | ||
| 4 | 4 | export const route: Route = { |
| 5 | 5 | method: "get", |
| 6 | 6 | path: "/api/v1/asked", |
| 7 | summary: "What people asked, and the caller's thought stream; answers { asked, thoughts } (ro scope)", | |
| 7 | summary: "What people asked, and the caller's thought stream", | |
| 8 | detail: "What people asked, and the caller's thought stream; answers { asked, thoughts } (ro scope)", | |
| 8 | 9 | auth: true, |
| 9 | 10 | role: "member", |
| 10 | 11 | query: { show: "string", order: "string", repo: "string" }, |
src/contract/openapi/routes/getApiV1AsksAdmin.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/asks/admin", |
| 6 | summary: "What this account asked whoever can change something to change, and what waits on this account to answer (ro scope); answers { items, toAnswer, next_cursor }, each item { want, subject, by, state, askedAt, answeredAt, says } with state asked, later or done; each of toAnswer also carries fix { href, label }, the exact control it is answered on; an ask is done by itself once the thing asked for is there, so polling this is how an agent waits", | |
| 6 | summary: "What this account asked whoever can change something to change", | |
| 7 | detail: "What this account asked whoever can change something to change, and what waits on this account to answer (ro scope); answers { items, toAnswer, next_cursor }, each item { want, subject, by, state, askedAt, answeredAt, says } with state asked, later or done; each of toAnswer also carries fix { href, label }, the exact control it is answered on; an ask is done by itself once the thing asked for is there, so polling this is how an agent waits", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | refusals: { |
src/contract/openapi/routes/getApiV1Boards.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/boards", |
| 6 | summary: "List the owner's boards; answers { boards: [{ slug, title, range, refresh, panels }] }. Site admin people only", | |
| 6 | summary: "List the owner's boards", | |
| 7 | detail: "List the owner's boards; answers { boards: [{ slug, title, range, refresh, panels }] }. Site admin people only", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "admin", |
| 9 | 10 | refuses: [401], |
src/contract/openapi/routes/getApiV1BoardsSlugPanelsId.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/boards/{slug}/panels/{id}", |
| 6 | summary: | |
| 6 | summary: "Read one panel's rows, as JSON or as a CSV table", | |
| 7 | detail: | |
| 7 | 8 | "Read one panel's rows; `id` is its place on the board from 0. Answers { board, panel, title, chart, rows, from, to, step }, or a CSV table with format=csv", |
| 8 | 9 | auth: true, |
| 9 | 10 | role: "admin", |
src/contract/openapi/routes/getApiV1BoardsSources.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/boards/sources", |
| 6 | summary: "List the sources a board query reads; answers { sources: [{ name, time, columns, docs? }] }", | |
| 6 | summary: "List the sources a board query reads", | |
| 7 | detail: "List the sources a board query reads; answers { sources: [{ name, time, columns, docs? }] }", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "admin", |
| 9 | 10 | refuses: [401], |
src/contract/openapi/routes/getApiV1Changelog.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/changelog", |
| 6 | summary: "What went live and what is on its way, as /changelog shows it, for anyone: version (the release number, or null for a build that is not a release, never the word dev), commit, short (its first 7 characters, null without a commit), liveSince (ISO: when this build began serving), releases (each version a public app's production deploy first served: repo, version, commit, subject, note, tests, servingMs, servedAt; ?repo narrows them), live and onItsWay rows (repo, number, title, at, and for the forge's own landings by: who built it, with: the models and people its commit credits) of public repositories; ?repo=all|owner/name, this forge's own by default (all when it has none); carries a weak ETag of the live version, the chosen repo and the rows, and a repeat sending If-None-Match gets 304 with no body and the same ETag and cache-control", | |
| 6 | summary: "What went live and what is on its way, as /changelog shows it, for anyone", | |
| 7 | detail: "What went live and what is on its way, as /changelog shows it, for anyone: version (the release number, or null for a build that is not a release, never the word dev), commit, short (its first 7 characters, null without a commit), liveSince (ISO: when this build began serving), releases (each version a public app's production deploy first served: repo, version, commit, subject, note, tests, servingMs, servedAt; ?repo narrows them), live and onItsWay rows (repo, number, title, at, and for the forge's own landings by: who built it, with: the models and people its commit credits) of public repositories; ?repo=all|owner/name, this forge's own by default (all when it has none); carries a weak ETag of the live version, the chosen repo and the rows, and a repeat sending If-None-Match gets 304 with no body and the same ETag and cache-control", | |
| 7 | 8 | alsoStatus: [304], |
| 8 | 9 | auth: false, |
| 9 | 10 | role: "anonymous", |
src/contract/openapi/routes/getApiV1CloudAccounts.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/cloud/accounts", |
| 6 | summary: "The forge's cloud accounts, each attached provider token with its use, verification, write permission and today's calls, never a secret; a forge administrator's, with a token that may write", | |
| 6 | summary: "The forge's cloud accounts", | |
| 7 | detail: "The forge's cloud accounts, each attached provider token with its use, verification, write permission and today's calls, never a secret; a forge administrator's, with a token that may write", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "admin", |
| 9 | 10 | refusals: { |
src/contract/openapi/routes/getApiV1Codes.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/codes", |
| 6 | summary: "The forge's gift codes (a person admin's token): each one's plan, note, uses and who redeemed it, newest first. Never the plain code. Answers { codes, plans }", | |
| 6 | summary: "The forge's gift codes", | |
| 7 | detail: "The forge's gift codes (a person admin's token): each one's plan, note, uses and who redeemed it, newest first. Never the plain code. Answers { codes, plans }", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "admin", |
| 9 | 10 | refusals: { not_found: "the token is not a person who administers the forge (404)" }, |
src/contract/openapi/routes/getApiV1Contribute.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/contribute", summary: "What an agent that arrives should know: { forge, bottleneck, welcomeLabel, issues, propose, telemetry }; issues are the open welcome-labelled ones in public repositories", auth: false, role: "anonymous" }; | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/contribute", summary: "What an agent that arrives should know", detail: "What an agent that arrives should know: { forge, bottleneck, welcomeLabel, issues, propose, telemetry }; issues are the open welcome-labelled ones in public repositories", auth: false, role: "anonymous" }; |
src/contract/openapi/routes/getApiV1ConversationFilesId.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/conversation/files/{id}", |
| 6 | summary: "Download one of the signed-in person's own attachments: always as an attachment with a fixed type (an image type or text/plain) and nosniff; another person's is not_found", | |
| 6 | summary: "Download one of the signed-in person's own attachments", | |
| 7 | detail: "Download one of the signed-in person's own attachments: always as an attachment with a fixed type (an image type or text/plain) and nosniff; another person's is not_found", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | refusals: { not_found: "no such attachment (404)" }, |
src/contract/openapi/routes/getApiV1ConversationTurns.ts +2 −1
| @@ -4,7 +4,8 @@ import { MAX_PAGE } from "../../../core/conversations.ts"; | ||
| 4 | 4 | export const route: Route = { |
| 5 | 5 | method: "get", |
| 6 | 6 | path: "/api/v1/conversation/turns", |
| 7 | summary: "The signed-in person's conversation with the forge's agent: the latest turns, oldest first, and whether an answer is being written now", | |
| 7 | summary: "The signed-in person's conversation with the forge's agent", | |
| 8 | detail: "The signed-in person's conversation with the forge's agent: the latest turns, oldest first, and whether an answer is being written now", | |
| 8 | 9 | auth: true, |
| 9 | 10 | role: "member", |
| 10 | 11 | query: { limit: limitTo(MAX_PAGE), before: "string", conversation: "string" }, |
src/contract/openapi/routes/getApiV1Conversations.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/conversations", |
| 6 | summary: "The signed-in person's conversations with the forge's agent, newest activity first; archived: 1 lists the put-away ones", | |
| 6 | summary: "The signed-in person's conversations with the forge's agent, newest activity first", | |
| 7 | detail: "The signed-in person's conversations with the forge's agent, newest activity first; archived: 1 lists the put-away ones", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | query: { archived: "string" }, |
src/contract/openapi/routes/getApiV1ConversationsIdBuild.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/conversations/{id}/build", |
| 6 | summary: "The app a conversation builds: its repository, branch, versions (the branch's commits past the default branch, numbered from v1), the preview address once there is a version, and whether it is published", | |
| 6 | summary: "The app a conversation builds", | |
| 7 | detail: "The app a conversation builds: its repository, branch, versions (the branch's commits past the default branch, numbered from v1), the preview address once there is a version, and whether it is published", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | reply: { repo: "string", versions: "array", published: "boolean" }, |
src/contract/openapi/routes/getApiV1ConversationsIdBuildVersionsNDiff.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/conversations/{id}/build/versions/{n}/diff", |
| 6 | summary: "The files and lines one version changed against the version before it; an unknown n is 404", | |
| 6 | summary: "The files and lines one version changed against the version before it", | |
| 7 | detail: "The files and lines one version changed against the version before it; an unknown n is 404", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | reply: { files: "array" }, |
src/contract/openapi/routes/getApiV1Credit.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/credit", |
| 6 | summary: | |
| 6 | summary: "Read the cap and spend of the credit a parent forge lent this one", | |
| 7 | detail: | |
| 7 | 8 | "On a forge its parent funds: the cap and the spend of the credit it was lent, asked of the parent afresh; answers { capUsd, spentUsd, says } (\"funded by its parent: $X of $200 left\"). 404 when no parent funds this forge", |
| 8 | 9 | auth: true, |
| 9 | 10 | role: "member", |
src/contract/openapi/routes/getApiV1CrewNow.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/crew/now", |
| 6 | summary: "What the crew is doing right now, as MCP `now` answers it: { items: [{ run, app, who, on, why, state, since, costUsd, ran? }], next_cursor: null } for the apps the caller may read; a planner that declined the direction and waits for the caller comes first (`run: null`, its words in `says`), then pulls waiting for their review", | |
| 6 | summary: "What the crew is doing right now, as MCP `now` answers it", | |
| 7 | detail: "What the crew is doing right now, as MCP `now` answers it: { items: [{ run, app, who, on, why, state, since, costUsd, ran? }], next_cursor: null } for the apps the caller may read; a planner that declined the direction and waits for the caller comes first (`run: null`, its words in `says`), then pulls waiting for their review", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | refusals: { unauthorized: "no valid credentials were sent" }, |
src/contract/openapi/routes/getApiV1CrewScorecard.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/crew/scorecard", |
| 6 | summary: "Read the crew's scorecard (a forge admin's, any token scope): { agents: [{ username, all, recent, splits }] }, where all and recent are { opened, landed, reviewRounds, redCheckRate, reverts, meanLandMs } or null, and each split adds model, prompt and its own recent; also modelDays (runs, landed and spend per model per day) and wastedDays: [{ day, wasted, runs, spentUsd }], the runs that ended on work not theirs to do", | |
| 6 | summary: "Read the crew's scorecard", | |
| 7 | detail: "Read the crew's scorecard (a forge admin's, any token scope): { agents: [{ username, all, recent, splits }] }, where all and recent are { opened, landed, reviewRounds, redCheckRate, reverts, meanLandMs } or null, and each split adds model, prompt and its own recent; also modelDays (runs, landed and spend per model per day) and wastedDays: [{ day, wasted, runs, spentUsd }], the runs that ended on work not theirs to do", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "admin", |
| 9 | 10 | refusals: { unauthorized: "no valid credentials were sent", forbidden: "the caller is not a forge admin" }, |
src/contract/openapi/routes/getApiV1CrewWeek.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/crew/week", |
| 6 | summary: "Read the crew's last 7 days (a forge admin's, any token scope): { days, members: [{ username, merged, returned, spentUsd, idle }] }, merged pulls, pulls returned by review and ledger spend per agent; idle is true when all three are nothing", | |
| 6 | summary: "Read the crew's last 7 days", | |
| 7 | detail: "Read the crew's last 7 days (a forge admin's, any token scope): { days, members: [{ username, merged, returned, spentUsd, idle }] }, merged pulls, pulls returned by review and ledger spend per agent; idle is true when all three are nothing", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "admin", |
| 9 | 10 | refusals: { unauthorized: "no valid credentials were sent", forbidden: "the caller is not a forge admin" }, |
src/contract/openapi/routes/getApiV1Explore.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import { limitTo, type Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/explore", summary: "Explore apps and repositories; `q` takes words and `kind:`/`owner:` filters; answers { query, items, next_cursor } (an app item carries forks, ships, likes and updatedAt, the time of its last ship, not of its last push, null when never shipped) (`limit` 1 to 100 rows a page, default 30; next_cursor null on the last; a bad `limit`, `sort` or `kind` is a 422 naming the field); cursor from next_cursor; a bad cursor is a 422 `invalid_cursor`; the answer carries an ETag (cache-control private, no-cache; vary authorization, cookie) that changes when anything listed changes, and a repeat sending it in If-None-Match gets 304 with no body", auth: false, role: "anonymous", alsoStatus: [304, 422], query: { q: "string", cursor: "string", limit: limitTo(100), sort: "string", kind: "string" } }; | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/explore", summary: "Explore apps and repositories", detail: "Explore apps and repositories; `q` takes words and `kind:`/`owner:` filters; answers { query, items, next_cursor } (an app item carries forks, ships, likes and updatedAt, the time of its last ship, not of its last push, null when never shipped) (`limit` 1 to 100 rows a page, default 30; next_cursor null on the last; a bad `limit`, `sort` or `kind` is a 422 naming the field); cursor from next_cursor; a bad cursor is a 422 `invalid_cursor`; the answer carries an ETag (cache-control private, no-cache; vary authorization, cookie) that changes when anything listed changes, and a repeat sending it in If-None-Match gets 304 with no body", auth: false, role: "anonymous", alsoStatus: [304, 422], query: { q: "string", cursor: "string", limit: limitTo(100), sort: "string", kind: "string" } }; |
src/contract/openapi/routes/getApiV1Family.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/family", |
| 6 | summary: "The forge's family: { parent, here, children, more }; the parent for anyone, the children for a site admin", | |
| 6 | summary: "The forge's family: { parent, here, children, more }", | |
| 7 | detail: "The forge's family: { parent, here, children, more }; the parent for anyone, the children for a site admin", | |
| 7 | 8 | auth: false, |
| 8 | 9 | role: "anonymous", |
| 9 | 10 | }; |
src/contract/openapi/routes/getApiV1Features.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/features", |
| 6 | summary: "Every app whose forge.json declares a `feature`, absorbed or not, with its typed settings and kept values (forge admin); answers { items, next_cursor }", | |
| 6 | summary: "Every app whose forge.json declares a `feature`", | |
| 7 | detail: "Every app whose forge.json declares a `feature`, absorbed or not, with its typed settings and kept values (forge admin); answers { items, next_cursor }", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | refusals: { not_found: "you are not a site admin" }, |
src/contract/openapi/routes/getApiV1FeaturesSlug.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/features/{slug}", |
| 6 | summary: "One app's feature: name, page, whether it is absorbed, and each setting with its type, value, default and the FORGE_SETTING_ name its process reads (for whoever may read the app)", | |
| 6 | summary: "Read one app's feature, its settings and whether it is absorbed", | |
| 7 | detail: "One app's feature: name, page, whether it is absorbed, and each setting with its type, value, default and the FORGE_SETTING_ name its process reads (for whoever may read the app)", | |
| 7 | 8 | auth: false, |
| 8 | 9 | role: "anonymous", |
| 9 | 10 | refusals: { not_found: "no such app, or one you may not read", not_a_feature: "the app's forge.json declares no feature (422)" }, |
src/contract/openapi/routes/getApiV1FeaturesSlugFeed.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/features/{slug}/feed", |
| 6 | summary: "The feed items about one app's feature, newest first, as {items, next_cursor} (for whoever may read the app)", | |
| 6 | summary: "The feed items about one app's feature", | |
| 7 | detail: "The feed items about one app's feature, newest first, as {items, next_cursor} (for whoever may read the app)", | |
| 7 | 8 | auth: false, |
| 8 | 9 | role: "anonymous", |
| 9 | 10 | refusals: { not_found: "no such app, or one you may not read", not_a_feature: "the app's forge.json declares no feature (422)" }, |
src/contract/openapi/routes/getApiV1Feed.ts +2 −1
| @@ -4,7 +4,8 @@ import { FEED_LIMIT_MAX } from "../../../feed/feed.ts"; | ||
| 4 | 4 | export const route: Route = { |
| 5 | 5 | method: "get", |
| 6 | 6 | path: "/api/v1/feed", |
| 7 | summary: "The caller's own feed, newest first (ro scope; never cached); answers { items, next cursor } to pass back as `cursor`; `before=now` (then each `next_cursor` as `before`) reads the log newest first instead, one event id as cursor, a page costing the same at any depth, no repeat or skip when posts arrive; without a `cursor` it also carries `digest`, home's \"Since you were here\" card, `{ heading, lines: [{ repo, says, href }] }` or null (a page with a cursor has no `digest` key); reading never counts as a visit; the ETag moves with the digest", | |
| 7 | summary: "The caller's own feed, newest first", | |
| 8 | detail: "The caller's own feed, newest first (ro scope; never cached); answers { items, next cursor } to pass back as `cursor`; `before=now` (then each `next_cursor` as `before`) reads the log newest first instead, one event id as cursor, a page costing the same at any depth, no repeat or skip when posts arrive; without a `cursor` it also carries `digest`, home's \"Since you were here\" card, `{ heading, lines: [{ repo, says, href }] }` or null (a page with a cursor has no `digest` key); reading never counts as a visit; the ETag moves with the digest", | |
| 8 | 9 | auth: true, |
| 9 | 10 | role: "member", |
| 10 | 11 | query: { limit: limitTo(FEED_LIMIT_MAX), cursor: "string", before: "string" }, |
src/contract/openapi/routes/getApiV1FeedChips.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/feed/chips", |
| 6 | summary: "The chips the caller switched off, kinds of post and people (ro scope; never cached); answers { kinds, people }", | |
| 6 | summary: "The chips the caller switched off, kinds of post and people", | |
| 7 | detail: "The chips the caller switched off, kinds of post and people (ro scope; never cached); answers { kinds, people }", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | refuses: [401], |
src/contract/openapi/routes/getApiV1FeedLikes.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/feed/likes", |
| 6 | summary: "The like ledger of one feed item, newest first, 50 a page (ro scope): `?item=` is a feed item id, `app` (owner/name) names the repository when the item is not an event; `before` is a seq to read the rows older than; answers { item, ledger: [{ seq, who, act, at }], more }, `more` true when older rows remain, `act` being like or unlike; an anonymous caller is told to sign in at /signin", | |
| 6 | summary: "The like ledger of one feed item, newest first, 50 a page", | |
| 7 | detail: "The like ledger of one feed item, newest first, 50 a page (ro scope): `?item=` is a feed item id, `app` (owner/name) names the repository when the item is not an event; `before` is a seq to read the rows older than; answers { item, ledger: [{ seq, who, act, at }], more }, `more` true when older rows remain, `act` being like or unlike; an anonymous caller is told to sign in at /signin", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | query: { item: "string", app: "string", before: "string" }, |
src/contract/openapi/routes/getApiV1Flags.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/flags", |
| 6 | 6 | summary: |
| 7 | "Every declared flag with why it exists", | |
| 8 | detail: | |
| 7 | 9 | "Every declared flag with why it exists, its default, the issue that owns removing it and its live value, as MCP `flags` answers (a person admin's token); answers { flags }", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "member", |
src/contract/openapi/routes/getApiV1FleetGraph.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/fleet/graph", |
| 6 | summary: "Spend and runs per repository by UTC hour (24 h) and day (14 d); `repo` (owner/name) repeats, else every repository the caller may write that spent lately", | |
| 6 | summary: "Spend and runs per repository by UTC hour and day", | |
| 7 | detail: "Spend and runs per repository by UTC hour (24 h) and day (14 d); `repo` (owner/name) repeats, else every repository the caller may write that spent lately", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | query: { repo: "string" }, |
src/contract/openapi/routes/getApiV1FleetRows.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/fleet/rows", |
| 6 | summary: "The rows a fleet query line selects, as /fleet shows them, only those the caller may read; answers { kind, columns, items }", | |
| 6 | summary: "The rows a fleet query line selects, as /fleet shows them, only those the caller may read", | |
| 7 | detail: "The rows a fleet query line selects, as /fleet shows them, only those the caller may read; answers { kind, columns, items }", | |
| 7 | 8 | auth: false, |
| 8 | 9 | role: "anonymous", |
| 9 | 10 | query: { q: "string", sort: "string" }, |
src/contract/openapi/routes/getApiV1Forge.ts +1 −1
| @@ -3,7 +3,7 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/forge", |
| 6 | summary: "A spawned forge's word about itself: { claimed, lastActivityAt, link? }; lastActivityAt, link ({ state, revokedAt, usedAt }) are null or absent, as is madeFrom ({ template, at }), unless the parent's secret is sent", | |
| 6 | summary: "A spawned forge's word about itself: { claimed, lastActivityAt, link? }", detail: "A spawned forge's word about itself: { claimed, lastActivityAt, link? }; lastActivityAt, link ({ state, revokedAt, usedAt }) are null or absent, as is madeFrom ({ template, at }), unless the parent's secret is sent", | |
| 7 | 7 | auth: false, |
| 8 | 8 | role: "anonymous", |
| 9 | 9 | refusals: { not_found: "404: this forge was not spawned" }, |
src/contract/openapi/routes/getApiV1ForgeEconomics.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/forge/economics", |
| 6 | summary: "The profit slider: position (0 cheapest to 100 most responsive), marginPct, the policy the position means (sleep windows in ms, idle-pull window, cloud spill share; null is never), placement (whether a cloud body takes bursts, the owned-node label, in words), the operator's prices in US dollars, this UTC month's cost so far ({ owned, cloud, storage, crew, total } in USD) and the last changes (a person admin's token)", | |
| 6 | summary: "Read the profit slider, the policy it means and this month's cost", | |
| 7 | detail: "The profit slider: position (0 cheapest to 100 most responsive), marginPct, the policy the position means (sleep windows in ms, idle-pull window, cloud spill share; null is never), placement (whether a cloud body takes bursts, the owned-node label, in words), the operator's prices in US dollars, this UTC month's cost so far ({ owned, cloud, storage, crew, total } in USD) and the last changes (a person admin's token)", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "admin", |
| 9 | 10 | refusals: { |
src/contract/openapi/routes/getApiV1ForgeView.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/forge/view", |
| 6 | summary: "The forge as one read-only picture for a reader that draws it: { counts: { apps, running, queued, waiting }, apps: [{ app, slug, access, running, queued }], runs: [the rows of /api/v1/crew/now; each run's state is its station], health: as /api/v1/health answers this caller, at } for the apps the caller may read. Any token scope reads it; it is built at most once per two seconds per caller and answers 304 to a held ETag, so polling it is cheap", | |
| 6 | summary: "The forge as one read-only picture for a reader that draws it", | |
| 7 | detail: "The forge as one read-only picture for a reader that draws it: { counts: { apps, running, queued, waiting }, apps: [{ app, slug, access, running, queued }], runs: [the rows of /api/v1/crew/now; each run's state is its station], health: as /api/v1/health answers this caller, at } for the apps the caller may read. Any token scope reads it; it is built at most once per two seconds per caller and answers 304 to a held ETag, so polling it is cheap", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | refusals: { unauthorized: "no valid credentials were sent" }, |
src/contract/openapi/routes/getApiV1Forges.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/forges", summary: "List the forges sent from here (a site admin's, ro scope): the client list /forges and the MCP forges tool show. answers { items, next_cursor: null }; each item has name, url, for, apps, sentAt, made, claimed (null when it did not answer), lastActivityAt (a person or the crew last did something there, never a heartbeat), claimedBy, claimedAt, keepBytes, archive (why it is proposed for archive, or null), running, reach, attention (silent, down, unclaimed or null), spendTodayUsd, ceilingUsd, month (this UTC month's spend from its own ledger, or where its chain is broken; null when it keeps none), size, use, lastHeartbeatAt and nextStep, and beside them what the list always carried: bodyId, done, createdAt, placement, placementNote and template (when one was chosen). what needs attention comes first", auth: true, role: "admin" }; | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/forges", summary: "List the forges sent from here", detail: "List the forges sent from here (a site admin's, ro scope): the client list /forges and the MCP forges tool show. answers { items, next_cursor: null }; each item has name, url, for, apps, sentAt, made, claimed (null when it did not answer), lastActivityAt (a person or the crew last did something there, never a heartbeat), claimedBy, claimedAt, keepBytes, archive (why it is proposed for archive, or null), running, reach, attention (silent, down, unclaimed or null), spendTodayUsd, ceilingUsd, month (this UTC month's spend from its own ledger, or where its chain is broken; null when it keeps none), size, use, lastHeartbeatAt and nextStep, and beside them what the list always carried: bodyId, done, createdAt, placement, placementNote and template (when one was chosen). what needs attention comes first", auth: true, role: "admin" }; |
src/contract/openapi/routes/getApiV1ForgesNameBill.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/forges/{name}/bill", |
| 6 | summary: "One month (?month=YYYY-MM, default this month) of a hosted forge's cost ledger and this forge's public key, signed, as one newline-delimited JSON file; `bun scripts/ledger-verify.ts --key <pub> <file>` checks it (the forge's owner only)", | |
| 6 | summary: "One month of a hosted forge's cost ledger and this forge's public key", | |
| 7 | detail: "One month (?month=YYYY-MM, default this month) of a hosted forge's cost ledger and this forge's public key, signed, as one newline-delimited JSON file; `bun scripts/ledger-verify.ts --key <pub> <file>` checks it (the forge's owner only)", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | refusals: { not_found: "the caller is not the person who owns the forge, or there is no such forge (404)", invalid_month: "month is not YYYY-MM (422)" }, |
src/contract/openapi/routes/getApiV1ForgesNamePlan.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/forges/{name}/plan", |
| 6 | summary: "A child forge's entitlement ({ forge, plan, status, periodEnd?, source }; a forge never granted a plan is active on the plan its size names) and its last changes (a person admin's token)", | |
| 6 | summary: "A child forge's entitlement and its last changes", | |
| 7 | detail: "A child forge's entitlement ({ forge, plan, status, periodEnd?, source }; a forge never granted a plan is active on the plan its size names) and its last changes (a person admin's token)", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "admin", |
| 9 | 10 | refusals: { not_found: "the token is not a person who administers the forge (404)", no_such_forge: "no child forge has this name (404)" }, |
src/contract/openapi/routes/getApiV1ForgesNameSandbox.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/forges/{name}/sandbox", |
| 6 | summary: | |
| 6 | summary: "Check what moving a child forge into a sandbox would meet", | |
| 7 | detail: | |
| 7 | 8 | "Before a child forge that runs inside this forge's own process is moved into a sandbox of its own (a site admin's, ro scope): what the move would meet, and nothing is changed. Answers { name, placement, where, blocked, held, repos, findings, size, diskMiB, sizeNeeded, says }. `findings` names, per repository, the hooks beyond the forge's own stubs and the config keys that run commands (names only, never contents): what this forge's process may have executed. `held` is why the automatic pass leaves it for the admin; `blocked` why it cannot be moved now; `sizeNeeded` the size its cell needs for what it holds on disk", |
| 8 | 9 | auth: true, |
| 9 | 10 | role: "admin", |
src/contract/openapi/routes/getApiV1ForgesRecipes.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/forges/recipes", |
| 6 | summary: "List the saved forge recipes of the person the token belongs to (read scope): each name with the config it spawns again", | |
| 6 | summary: "List your saved forge recipes", | |
| 7 | detail: "List the saved forge recipes of the person the token belongs to (read scope): each name with the config it spawns again", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | refusals: { forbidden: "the token is not a person (403)" }, |
src/contract/openapi/routes/getApiV1Front.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/front", summary: "The front page a stranger is shown: { featured, apps, total }, each entry { repo, description, url, state, picture, pinned, score, signals }; a site admin also gets `picks`", auth: false, role: "anonymous" }; | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/front", summary: "The front page a stranger is shown", detail: "The front page a stranger is shown: { featured, apps, total }, each entry { repo, description, url, state, picture, pinned, score, signals }; a site admin also gets `picks`", auth: false, role: "anonymous" }; |
src/contract/openapi/routes/getApiV1Health.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/health", |
| 6 | 6 | summary: |
| 7 | "How the forge is, uncached", | |
| 8 | detail: | |
| 7 | 9 | "How the forge is, uncached; anyone may ask, a stranger is told little, the release probe and a site admin the whole of it. Every answer carries release, the running release as x.y.z or null when the build names none (version is unchanged and may say dev), and schedules {overdue, oldestSeconds, total, ran}: how many unpaused schedules are more than five minutes past due, the age in seconds of the most overdue (0 when none), how many unpaused schedules there are and how many of them have a recorded run, counts only, naming no app or repository", |
| 8 | 10 | auth: false, |
| 9 | 11 | role: "anonymous", |
src/contract/openapi/routes/getApiV1Here.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/here", summary: "The manifest of what you can do at `path` (default /), given who you are (`you` is `{as: start, user, repo}` for a start token, whose `can` is push, read, report): { here, you, can, mcp, docs }; never cached", auth: false, role: "anonymous", query: { path: "string" }, refusals: { invalid_token: "401, a bearer or basic credential was sent and matches no account or token: start again (POST /api/v1/start) or sign in; send none to be anonymous", not_found: "404: the path names no page you can read" } }; | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/here", summary: "The manifest of what you can do at `path`, given who you are", detail: "The manifest of what you can do at `path` (default /), given who you are (`you` is `{as: start, user, repo}` for a start token, whose `can` is push, read, report): { here, you, can, mcp, docs }; never cached", auth: false, role: "anonymous", query: { path: "string" }, refusals: { invalid_token: "401, a bearer or basic credential was sent and matches no account or token: start again (POST /api/v1/start) or sign in; send none to be anonymous", not_found: "404: the path names no page you can read" } }; |
src/contract/openapi/routes/getApiV1Keeper.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/keeper", |
| 6 | summary: "The release keeper's releases, holds and what blocks the next cut, for the forge's administrators and its repository's readers", | |
| 6 | summary: "The release keeper's releases", | |
| 7 | detail: "The release keeper's releases, holds and what blocks the next cut, for the forge's administrators and its repository's readers", | |
| 7 | 8 | auth: false, |
| 8 | 9 | role: "anonymous", |
| 9 | 10 | refusals: { |
src/contract/openapi/routes/getApiV1MaintenanceDuties.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/maintenance/duties", |
| 6 | 6 | summary: |
| 7 | "Each maintenance duty with whether it is paused, and why and by whom", | |
| 8 | detail: | |
| 7 | 9 | "Each maintenance duty with whether it is paused, and why and by whom (a forge admin's token); answers { duties }", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "admin", |
src/contract/openapi/routes/getApiV1MaintenanceRuns.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/maintenance/runs", |
| 6 | 6 | summary: |
| 7 | "The latest maintenance duty runs", | |
| 8 | detail: | |
| 7 | 9 | "The latest maintenance duty runs, newest first, each with its findings, actions and probes (a forge admin's token; ?limit= up to 100); answers { runs }", |
| 8 | 10 | auth: true, |
| 9 | 11 | alsoStatus: [422], |
src/contract/openapi/routes/getApiV1MigrateJobStream.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/migrate/{job}/stream", |
| 6 | 6 | summary: |
| 7 | "Watch a migration job as an event stream", | |
| 8 | detail: | |
| 7 | 9 | "Watch a migration job as an event stream (text/event-stream, not JSON): one `migrate.<stage>` event per stage with the job as data, closing after done or failed", |
| 8 | 10 | auth: true, |
| 9 | 11 | role: "member", |
src/contract/openapi/routes/getApiV1OffersReceipt.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/offers/{receipt}", |
| 6 | 6 | summary: |
| 7 | "Read the state of one offered patch by the random receipt its offer returned", | |
| 8 | detail: | |
| 7 | 9 | "Read the state of one offered patch by the random receipt its offer returned, without an account; answers only that offer's own state, and an unknown receipt is a 404", |
| 8 | 10 | auth: false, |
| 9 | 11 | role: "anonymous", |
src/contract/openapi/routes/getApiV1OrgsOrg.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/orgs/{org}", summary: "Read one organization's public profile plus `teams`, the teams the caller may see: all for an org admin, only their own for a member, [] for a stranger or anonymous caller", auth: false, role: "anonymous", refuses: [404] }; | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/orgs/{org}", summary: "Read one organization's public profile plus `teams`, the teams the caller may see", detail: "Read one organization's public profile plus `teams`, the teams the caller may see: all for an org admin, only their own for a member, [] for a stranger or anonymous caller", auth: false, role: "anonymous", refuses: [404] }; |
src/contract/openapi/routes/getApiV1OrgsOrgTeams.ts +1 −1
| @@ -1,4 +1,4 @@ | ||
| 1 | 1 | import { type Route, limitTo } from "../shared.ts"; |
| 2 | 2 | import { LIST_LIMIT_MAX } from "../../../core/issues.ts"; |
| 3 | 3 | |
| 4 | export const route: Route = { method: "get", path: "/api/v1/orgs/{org}/teams", summary: "List an organization's teams; answers { items, next_cursor }, paged by `limit` and `cursor`: all for an org admin, only the caller's own teams for a member, [] for a stranger or anonymous caller; the 200 carries a weak etag of the exact JSON and cache-control private, no-cache, and a repeat sending If-None-Match gets 304 with no body once access is checked", auth: false, role: "anonymous", alsoStatus: [304], query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, refuses: [404] }; | |
| 4 | export const route: Route = { method: "get", path: "/api/v1/orgs/{org}/teams", summary: "List an organization's teams", detail: "List an organization's teams; answers { items, next_cursor }, paged by `limit` and `cursor`: all for an org admin, only the caller's own teams for a member, [] for a stranger or anonymous caller; the 200 carries a weak etag of the exact JSON and cache-control private, no-cache, and a repeat sending If-None-Match gets 304 with no body once access is checked", auth: false, role: "anonymous", alsoStatus: [304], query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, refuses: [404] }; |
src/contract/openapi/routes/getApiV1OrgsOrgTeamsTeamMembers.ts +1 −1
| @@ -1,4 +1,4 @@ | ||
| 1 | 1 | import { type Route, limitTo } from "../shared.ts"; |
| 2 | 2 | import { LIST_LIMIT_MAX } from "../../../core/issues.ts"; |
| 3 | 3 | |
| 4 | export const route: Route = { method: "get", path: "/api/v1/orgs/{org}/teams/{team}/members", summary: "List a team's members as public profiles; answers { items, next_cursor }, paged by `limit` and `cursor`; 404 when the caller may not see the team; the 200 carries a weak etag of the exact JSON and cache-control private, no-cache, and a repeat sending If-None-Match gets 304 with no body once access is checked", auth: false, role: "anonymous", alsoStatus: [304], query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, refuses: [404] }; | |
| 4 | export const route: Route = { method: "get", path: "/api/v1/orgs/{org}/teams/{team}/members", summary: "List a team's members as public profiles", detail: "List a team's members as public profiles; answers { items, next_cursor }, paged by `limit` and `cursor`; 404 when the caller may not see the team; the 200 carries a weak etag of the exact JSON and cache-control private, no-cache, and a repeat sending If-None-Match gets 304 with no body once access is checked", auth: false, role: "anonymous", alsoStatus: [304], query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, refuses: [404] }; |
src/contract/openapi/routes/getApiV1Packs.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/packs", summary: "The curated packs: { items: [{ name, title, pitch, brief, repos, shown }] }; shown is the public repos on this forge; repos (the list as kept) and left_out come only to a person admin", auth: false, role: "anonymous" }; | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/packs", summary: "The curated packs: { items: [{ name, title, pitch, brief, repos, shown }] }", detail: "The curated packs: { items: [{ name, title, pitch, brief, repos, shown }] }; shown is the public repos on this forge; repos (the list as kept) and left_out come only to a person admin", auth: false, role: "anonymous" }; |
src/contract/openapi/routes/getApiV1PacksName.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/packs/{name}", summary: "One curated pack: { name, title, pitch, brief, shown } (shown: the public repos on this forge), and for a person admin also repos, left_out and the history of who changed what and when", auth: false, role: "anonymous", refusals: { not_found: "404: no such pack" }, refuses: [404] }; | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/packs/{name}", summary: "One curated pack", detail: "One curated pack: { name, title, pitch, brief, shown } (shown: the public repos on this forge), and for a person admin also repos, left_out and the history of who changed what and when", auth: false, role: "anonymous", refusals: { not_found: "404: no such pack" }, refuses: [404] }; |
src/contract/openapi/routes/getApiV1PassportHealth.ts +2
| @@ -4,6 +4,8 @@ export const route: Route = { | ||
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/passport/health", |
| 6 | 6 | summary: |
| 7 | "The forge's public health, for a caller holding a passport rather than a token", | |
| 8 | detail: | |
| 7 | 9 | "The forge's public health, for a caller holding a passport (`Authorization: Passport <token>`, audience `forge`, scope `health:read`) rather than a token; answers the same body as the anonymous health, uncached", |
| 8 | 10 | auth: false, |
| 9 | 11 | role: "anonymous", |
src/contract/openapi/routes/getApiV1Plans.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/plans", summary: "The plans (free, small, medium, large by default): key, name, says, size, priceUsd a month, creditUsd a month, forges one person may hold; beside them startCreditUsd (crew credit lent once to a new free forge that brings no model key, the spawn.included_credit_usd limit), graceDays (days a lapsed payment has, the billing.grace_days setting) and lapse sleep (the forge then sleeps and keeps its data); public, revalidated by ETag, no secrets", auth: false, role: "anonymous" }; | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/plans", summary: "List the plans, with their price, credit and forge allowance", detail: "The plans (free, small, medium, large by default): key, name, says, size, priceUsd a month, creditUsd a month, forges one person may hold; beside them startCreditUsd (crew credit lent once to a new free forge that brings no model key, the spawn.included_credit_usd limit), graceDays (days a lapsed payment has, the billing.grace_days setting) and lapse sleep (the forge then sleeps and keeps its data); public, revalidated by ETag, no secrets", auth: false, role: "anonymous" }; |
src/contract/openapi/routes/getApiV1ReachAsks.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/reach/asks", |
| 6 | summary: "On a forge hosted by another: what this account asked the host to let the forge reach, and how each ask stands (ro scope); answers { items, next_cursor }, each item { host, port, why, state, askedAt, answeredAt, retries, outcome, says } with state unsent, asked, later, allowed or refused; the host is asked first, at most every few seconds, so polling this is how an agent waits for the answer", | |
| 6 | summary: "List what this forge asked its host to let it reach", | |
| 7 | detail: "On a forge hosted by another: what this account asked the host to let the forge reach, and how each ask stands (ro scope); answers { items, next_cursor }, each item { host, port, why, state, askedAt, answeredAt, retries, outcome, says } with state unsent, asked, later, allowed or refused; the host is asked first, at most every few seconds, so polling this is how an agent waits for the answer", | |
| 7 | 8 | auth: true, |
| 8 | 9 | role: "member", |
| 9 | 10 | refusals: { |
src/contract/openapi/routes/getApiV1Releases.ts +2 −1
| @@ -3,7 +3,8 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/releases", |
| 6 | summary: "The kept releases newest first, for the forge's administrators and its repository's readers; ?shipped=true is what went live and what is on its way, for anyone; the 200 carries a weak etag of the JSON sent (shipped: cache-control public, max-age=60; kept releases: private, no-cache with vary authorization, cookie), a repeat sending If-None-Match gets 304 with no body, and a 403 or 422 carries no etag", | |
| 6 | summary: "The kept releases newest first", | |
| 7 | detail: "The kept releases newest first, for the forge's administrators and its repository's readers; ?shipped=true is what went live and what is on its way, for anyone; the 200 carries a weak etag of the JSON sent (shipped: cache-control public, max-age=60; kept releases: private, no-cache with vary authorization, cookie), a repeat sending If-None-Match gets 304 with no body, and a 403 or 422 carries no etag", | |
| 7 | 8 | alsoStatus: [304], |
| 8 | 9 | auth: false, |
| 9 | 10 | role: "anonymous", |
src/contract/openapi/routes/getApiV1Repos.ts +1 −1
| @@ -1,4 +1,4 @@ | ||
| 1 | 1 | import { REPO_LIST_SHAPES, type Route, limitTo } from "../shared.ts"; |
| 2 | 2 | import { LIST_LIMIT_MAX } from "../../../core/issues.ts"; |
| 3 | 3 | |
| 4 | export const route: Route = { method: "get", path: "/api/v1/repos", summary: "List repositories the viewer can see; tagged with a weak ETag, and a repeat with If-None-Match gets 304 until a listed repository changes or the viewer gains or loses write access; each item is the reader's fields to anyone who cannot write that repository, the whole object to who can", auth: false, role: "anonymous", alsoStatus: [304], replyShapes: REPO_LIST_SHAPES, query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, refusals: { invalid_limit: "limit is not a whole number from 1 to 200 (422)", invalid_cursor: "cursor is not the next_cursor of a previous page (422)" } }; | |
| 4 | export const route: Route = { method: "get", path: "/api/v1/repos", summary: "List repositories the viewer can see", detail: "List repositories the viewer can see; tagged with a weak ETag, and a repeat with If-None-Match gets 304 until a listed repository changes or the viewer gains or loses write access; each item is the reader's fields to anyone who cannot write that repository, the whole object to who can", auth: false, role: "anonymous", alsoStatus: [304], replyShapes: REPO_LIST_SHAPES, query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, refusals: { invalid_limit: "limit is not a whole number from 1 to 200 (422)", invalid_cursor: "cursor is not the next_cursor of a previous page (422)" } }; |
314 more files not shown.
new above
offline
Clipped mid-sentence: "Read who comes back; query". Make it a whole line, e.g. "Read who comes back: new and returning visitors per day". Check every generated summary for the same cut.