tenseleyflow/shithub / 1938837

+# Admin (site-admin only)

+

+> **Planned.** The admin API is not exposed yet. Site-admin

+> actions today are reachable through the `/admin/` web UI and

+> the `shithubd admin` CLI subcommands.

+

+The site-admin surface is intentionally narrow: most operator

+actions go through the CLI (`shithubd admin …`) where they're

+auditable from journal logs. The planned API here exists for

+automation that's already authenticated as a site admin (e.g.,

+an SSO/SCIM bridge).

+

+## Planned routes

+

+| Method | Path                                     | Scope          | Purpose                          |

+|--------|------------------------------------------|----------------|----------------------------------|

+| GET    | `/api/v1/admin/users`                    | site-admin     | List users (paginated).          |

+| GET    | `/api/v1/admin/users/{id}`               | site-admin     | One user, with admin-only fields.|

+| POST   | `/api/v1/admin/users/{id}/suspend`       | site-admin     | Freeze the account.              |

+| POST   | `/api/v1/admin/users/{id}/reinstate`     | site-admin     | Un-freeze.                       |

+| POST   | `/api/v1/admin/users/{id}/reset-password`| site-admin     | Force a password reset email.    |

+| POST   | `/api/v1/admin/users/{id}/site-admin`    | site-admin     | Grant or revoke site-admin bit.  |

+

+## Authorization

+

+A regular PAT — even one held by a user who is a site admin — is

+**not enough** by itself; the admin endpoints require both:

+

+- The token's owner has the `is_site_admin` flag set.

+- The token has the `admin:site` scope (separate from `admin:org`).

+

+Both checks must pass; either alone returns 403.

+

+## Audit

+

+Every admin API call writes to the same `admin_audit_log` the

+web admin UI uses. Each row carries the calling site admin's id,

+the target id, the action, and the request IP.

+# Authentication

+

+shithub's API is PAT-only. There is no OAuth / device-flow / JWT

+issuance endpoint today.

+

+## Header

+

+```

+Authorization: Bearer shp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

+```

+

+`Authorization: token shp_…` is accepted as a synonym for tools

+that hard-code GitHub's older syntax.

+

+## Token format

+

+PATs are 40 characters of base32 with the `shp_` prefix. They

+match the regex:

+

+```

+shp_[A-Za-z0-9]{40}

+```

+

+Secret-scanning tools (GitHub's, GitGuardian's, etc.) recognize

+this prefix.

+

+## Failure modes

+

+| Status | Body                              | Cause                                                |

+|-------:|-----------------------------------|------------------------------------------------------|

+|    401 | `{"error":"unauthenticated"}`     | Missing or malformed header.                          |

+|    401 | `{"error":"invalid token"}`       | Token doesn't exist, was revoked, or has expired.    |

+|    401 | `{"error":"account suspended"}`   | The owning account has been suspended by an admin.   |

+|    403 | `{"error":"insufficient scope"}`  | Token is valid but lacks the scope this route needs. |

+

+## Sessions

+

+The web UI uses session cookies, not PATs. Session cookies are

+**not accepted** on `/api/v1/` — the API is PAT-only. This is a

+deliberate choice: it keeps CSRF concerns off the API surface

+and means every API caller is identified by an auditable token.

+

+## Creating a token programmatically

+

+There is no API for creating PATs; tokens are only created from

+the web UI. This is intentional — the create-PAT surface is the

+account's most security-sensitive non-password operation.

+

+## Future

+

+OAuth-style application authorizations (`client_id` + `client_

+secret`, `code` exchange, refresh tokens) are planned post-MVP.

+For now, instruct human users to mint a PAT from their settings

+and supply it to your app via the operator's secret-management

+flow.

+# Status checks

+

+External CI systems publish status into shithub via the check-runs

+API. Branch-protection rules can require named contexts to pass

+before a PR merges.

+

+## Concepts

+

+- A **check run** is one invocation: `(repo, head_sha, name)`

+  with a state and metadata.

+- A **check suite** is the bag of check runs for one head SHA;

+  shithub computes it server-side.

+- Branch protection's "required status checks" matches by **name**

+  on the head commit.

+

+## Create a check run

+

+```

+POST /api/v1/repos/{owner}/{repo}/check-runs

+```

+

+Required scope: `repo` (write).

+

+### Request body

+

+```json

+{

+  "name":       "ci/lint",

+  "head_sha":   "8c4e3f2a1b…",

+  "status":     "in_progress",

+  "started_at": "2026-05-09T16:00:00Z",

+  "details_url": "https://ci.example/runs/12345",

+  "external_id": "12345",

+  "output": {

+    "title":   "Lint",

+    "summary": "Running golangci-lint",

+    "text":    "..."

+  }

+}

+```

+

+| Field          | Required | Notes                                                      |

+|----------------|----------|------------------------------------------------------------|

+| `name`         | yes      | The context name. Match this on branch-protection rules.   |

+| `head_sha`     | yes      | 40-char SHA-1 of the commit being checked.                 |

+| `status`       | no       | `queued`, `in_progress`, `completed`. Default `queued`.    |

+| `conclusion`   | iff `status=completed` | `success`, `failure`, `neutral`, `cancelled`, `timed_out`, `action_required`. |

+| `started_at`   | no       | RFC 3339.                                                  |

+| `completed_at` | iff `status=completed` | RFC 3339.                                       |

+| `details_url`  | no       | Where humans go to inspect the run.                        |

+| `external_id`  | no       | Your system's identifier; echoed back on read.             |

+| `output`       | no       | `{title, summary, text}`. Summary is markdown.             |

+

+### Response

+

+`201 Created` with the full check-run resource:

+

+```json

+{

+  "id":         9876,

+  "name":       "ci/lint",

+  "head_sha":   "8c4e3f2a1b…",

+  "status":     "in_progress",

+  "conclusion": null,

+  "started_at": "2026-05-09T16:00:00Z",

+  "details_url": "https://ci.example/runs/12345",

+  "external_id": "12345",

+  "output":     { "title": "Lint", "summary": "Running golangci-lint" }

+}

+```

+

+## Update a check run

+

+```

+PATCH /api/v1/repos/{owner}/{repo}/check-runs/{id}

+```

+

+Required scope: `repo` (write).

+

+Same body shape as create; partial. Typical use: flip

+`status: "completed"` with a `conclusion`.

+

+### Conclusion semantics

+

+| Conclusion        | Effect on PR merge gate                                |

+|-------------------|--------------------------------------------------------|

+| `success`         | Counts as passing.                                     |

+| `failure`         | Blocks merge.                                          |

+| `neutral`         | Doesn't block; doesn't count as passing either.        |

+| `cancelled`       | Blocks merge.                                          |

+| `timed_out`       | Blocks merge.                                          |

+| `action_required` | Blocks merge with a human-action signal.               |

+

+## List check runs for a commit

+

+```

+GET /api/v1/repos/{owner}/{repo}/commits/{sha}/check-runs

+```

+

+Required scope: `repo:read`.

+

+Returns the most recent check run **per name** on this commit.

+Older runs are still in the database (audit) but not in this

+listing.

+

+```json

+{

+  "total_count": 2,

+  "check_runs": [

+    {"id": 9876, "name": "ci/lint",  "status": "completed", "conclusion": "success", ...},

+    {"id": 9877, "name": "ci/test",  "status": "in_progress", ...}

+  ]

+}

+```

+

+## List check suites for a commit

+

+```

+GET /api/v1/repos/{owner}/{repo}/commits/{sha}/check-suites

+```

+

+Required scope: `repo:read`.

+

+Returns the rolled-up suite view per `head_sha`:

+

+```json

+{

+  "total_count": 1,

+  "check_suites": [

+    {

+      "head_sha":  "8c4e3f2a1b…",

+      "status":    "in_progress",

+      "conclusion": null,

+      "checks_url": "/api/v1/repos/owner/repo/commits/8c4e3f2a1b…/check-runs"

+    }

+  ]

+}

+```

+

+## Idempotency

+

+Check-run creates with the same `(repo, head_sha, name,

+external_id)` are coalesced — re-publishing the same run from a

+retried CI job is safe.

+

+## Permissions

+

+The PAT must belong to a user with **write access** to the repo.

+Bot accounts representing CI runners are the typical pattern;

+they're regular shithub accounts with PATs scoped to `repo` and

+nothing else.

+# Issues

+

+> **Planned.** Issues over the API are not yet shipped. The web

+> UI is the only authoring surface today.

+

+## Planned routes

+

+| Method | Path                                                   | Scope        |

+|--------|--------------------------------------------------------|--------------|

+| GET    | `/api/v1/repos/{owner}/{repo}/issues`                  | `repo:read`  |

+| GET    | `/api/v1/repos/{owner}/{repo}/issues/{number}`         | `repo:read`  |

+| POST   | `/api/v1/repos/{owner}/{repo}/issues`                  | `repo`       |

+| PATCH  | `/api/v1/repos/{owner}/{repo}/issues/{number}`         | `repo`       |

+| GET    | `/api/v1/repos/{owner}/{repo}/issues/{number}/comments`| `repo:read`  |

+| POST   | `/api/v1/repos/{owner}/{repo}/issues/{number}/comments`| `repo`       |

+| PATCH  | `/api/v1/repos/{owner}/{repo}/issues/comments/{id}`    | `repo`       |

+| DELETE | `/api/v1/repos/{owner}/{repo}/issues/comments/{id}`    | `repo`       |

+

+Filters on the list endpoint will mirror the web filters

+(`state`, `author`, `assignee`, `label`, `milestone`, `since`,

+`sort`, `direction`).

+

+## Markdown rendering

+

+Posted bodies are stored as raw markdown. Rendering happens at

+read time, with the same `internal/markdown` pipeline the web UI

+uses, so an API consumer sees the same HTML the browser would.

+# API overview

+

+shithub exposes a small REST API at `/api/v1/`. It's

+PAT-authenticated, JSON-bodied, and CSRF-exempt.

+

+> **Status.** The API is intentionally narrow today. Endpoints

+> currently shipped: `GET /api/v1/user`, the

+> `/api/v1/repos/{owner}/{repo}/check-runs` family, and the

+> `/api/v1/user/starred*` stars endpoints. Other sections of this

+> reference (Issues, Pull requests, Webhooks, etc.) describe the

+> **planned** shape and will land in subsequent sprints. Pages

+> that document planned-only endpoints carry a banner.

+

+## Authentication

+

+Every API request requires a personal access token. See

+[Personal access tokens](../user/personal-access-tokens.md) for

+how to create one.

+

+```

+Authorization: Bearer shp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

+```

+

+`Authorization: token shp_…` is also accepted as a synonym.

+

+A request with no `Authorization` header — or with an invalid /

+expired / revoked PAT — returns `401 Unauthorized` with:

+

+```json

+{"error": "unauthenticated"}

+```

+

+A request whose PAT lacks the scope a route requires returns

+`403 Forbidden` with:

+

+```json

+{"error": "insufficient scope"}

+```

+

+## Scopes

+

+Every route declares the scope(s) a token must hold. See

+[scopes table](../user/personal-access-tokens.md#scopes).

+

+Scopes are **grants only** — a token cannot do something the

+underlying user cannot. Holding `repo` does not let a token push

+to a repo the user has no access to.

+

+## Conventions

+

+- **Base URL:** `https://<your-instance>/api/v1/`

+- **Content type:** `application/json; charset=utf-8` for

+  request bodies and responses.

+- **Error responses:** `{"error": "<short message>"}` with a

+  conventional HTTP status.

+- **Cache-Control:** every API response sets `no-store`.

+- **Pagination:** list endpoints accept `?per_page=` (default 30,

+  max 100) and return a `Link:` header with `next`, `prev`,

+  `first`, `last` URLs (RFC 5988). Cursor pagination on hot lists

+  uses `?cursor=…` and returns the next cursor in the `Link:`

+  header.

+- **Body cap:** request bodies are capped at 256 KiB. Larger

+  payloads return `413`.

+- **Rate limits:** every response includes `X-RateLimit-Limit`,

+  `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers (Unix

+  timestamp). Exceeding the limit returns `429`.

+

+## Versioning

+

+The path prefix `/api/v1/` is the version. Backwards-incompatible

+changes will land under `/api/v2/`. Additions (new endpoints, new

+fields on responses) are not breaking and land under v1.

+

+## Date format

+

+All timestamps are RFC 3339 UTC: `2026-05-09T16:30:00Z`.

+

+## ID stability

+

+Numeric IDs are stable for the life of the row; reusing a name

+slot doesn't reuse the ID. URLs that take a `{owner}` and `{repo}`

+will redirect after a rename — but external callers should

+prefer numeric IDs where the API exposes them.

+# Pull requests

+

+> **Planned.** Pull request endpoints are not yet shipped.

+

+## Planned routes

+

+| Method | Path                                                     | Scope        |

+|--------|----------------------------------------------------------|--------------|

+| GET    | `/api/v1/repos/{owner}/{repo}/pulls`                     | `repo:read`  |

+| GET    | `/api/v1/repos/{owner}/{repo}/pulls/{number}`            | `repo:read`  |

+| POST   | `/api/v1/repos/{owner}/{repo}/pulls`                     | `repo`       |

+| PATCH  | `/api/v1/repos/{owner}/{repo}/pulls/{number}`            | `repo`       |

+| GET    | `/api/v1/repos/{owner}/{repo}/pulls/{number}/files`      | `repo:read`  |

+| GET    | `/api/v1/repos/{owner}/{repo}/pulls/{number}/commits`    | `repo:read`  |

+| GET    | `/api/v1/repos/{owner}/{repo}/pulls/{number}/reviews`    | `repo:read`  |

+| POST   | `/api/v1/repos/{owner}/{repo}/pulls/{number}/reviews`    | `repo`       |

+| PUT    | `/api/v1/repos/{owner}/{repo}/pulls/{number}/merge`      | `repo`       |

+| GET    | `/api/v1/repos/{owner}/{repo}/pulls/{number}/comments`   | `repo:read`  |

+| POST   | `/api/v1/repos/{owner}/{repo}/pulls/{number}/comments`   | `repo`       |

+

+The merge endpoint is gated by branch protection: status checks,

+required reviewers, and conversation-resolution rules apply

+identically to API-driven and UI-driven merges.

+# Repositories

+

+> **Planned.** The repository CRUD API surface is not yet

+> shipped. Today the repo lifecycle is driven through the web UI

+> and the `shithubd` CLI. The shape below is the **planned** v1

+> surface; it will land in a follow-up sprint.

+

+## Planned routes

+

+| Method | Path                                        | Scope        | Purpose                       |

+|--------|---------------------------------------------|--------------|-------------------------------|

+| GET    | `/api/v1/repos/{owner}/{repo}`              | `repo:read`  | Get one repo.                 |

+| POST   | `/api/v1/user/repos`                        | `repo`       | Create a repo under the user. |

+| POST   | `/api/v1/orgs/{org}/repos`                  | `repo,admin:org` | Create a repo under an org. |

+| PATCH  | `/api/v1/repos/{owner}/{repo}`              | `repo`       | Edit settings.                |

+| DELETE | `/api/v1/repos/{owner}/{repo}`              | `repo`       | Delete (with confirmation).   |

+| GET    | `/api/v1/repos/{owner}/{repo}/branches`     | `repo:read`  | List branches.                |

+| GET    | `/api/v1/repos/{owner}/{repo}/branches/{branch}/protection` | `repo:read` | Get branch protection rules. |

+| PUT    | `/api/v1/repos/{owner}/{repo}/branches/{branch}/protection` | `repo`     | Replace branch protection.   |

+

+The web UI's behavior is the de-facto specification — when these

+endpoints land, they implement the same checks (visibility, name

+collisions, owner-permissions, soft-delete grace) that the web

+forms enforce.

+

+## Today

+

+Until the API ships, scripted repo lifecycle is best done via

+the `shithubd` operator CLI on the host (operator-only) or

+through HTML form submission with a session cookie (per-user but

+not API-shaped).

+# Search

+

+> **Planned.** Search over the API is not shipped yet. The web UI's

+> `/search` is the only entry point today.

+

+## Planned routes

+

+| Method | Path                              | Scope                          |

+|--------|-----------------------------------|--------------------------------|

+| GET    | `/api/v1/search/code`             | None (public corpus only without `repo:read`); `repo:read` to include private. |

+| GET    | `/api/v1/search/repositories`     | Same scoping.                  |

+| GET    | `/api/v1/search/issues`           | Same scoping.                  |

+| GET    | `/api/v1/search/users`            | None.                          |

+

+Query parameters:

+

+- `q=` — search query, with the same operators as

+  [Search (user docs)](../user/search.md).

+- `sort=` — `created`, `updated`, `stars`, `relevance` (default).

+- `order=` — `asc`, `desc`.

+- `per_page=`, `cursor=`.

+

+Response shape (proposed):

+

+```json

+{

+  "total_count": 142,

+  "items": [

+    { /* type-dependent record */ }

+  ]

+}

+```

+

+The total is **counted to a cap** (10000) — for larger result

+sets the API returns "10000+" semantics rather than counting

+exactly. Consumers that need totals should narrow the query.

+

+## Visibility

+

+Search results are filtered by the requesting PAT's user's

+visibility, identical to the web UI's behavior. A token cannot

+see a result it would not see in a browser logged in as the

+same user.

+# 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

+

+```json

+{

+  "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`.

+# Webhooks

+

+The webhook **delivery format** (payloads, signing) is shipped

+and stable. The webhook **management API** (CRUD over webhooks

+on a repo) is planned.

+

+## Delivery format

+

+See [Webhooks (user docs)](../user/webhooks.md) for the full

+delivery contract — headers, body framing, signature verification,

+retries, idempotency.

+

+The user-docs page is intentionally the canonical place; an API

+consumer building a subscriber endpoint reads the same material.

+

+## Management API (planned)

+

+| Method | Path                                                      | Scope        |

+|--------|-----------------------------------------------------------|--------------|

+| GET    | `/api/v1/repos/{owner}/{repo}/hooks`                      | `webhooks`   |

+| POST   | `/api/v1/repos/{owner}/{repo}/hooks`                      | `webhooks`   |

+| GET    | `/api/v1/repos/{owner}/{repo}/hooks/{id}`                 | `webhooks`   |

+| PATCH  | `/api/v1/repos/{owner}/{repo}/hooks/{id}`                 | `webhooks`   |

+| DELETE | `/api/v1/repos/{owner}/{repo}/hooks/{id}`                 | `webhooks`   |

+| POST   | `/api/v1/repos/{owner}/{repo}/hooks/{id}/pings`           | `webhooks`   |

+| GET    | `/api/v1/repos/{owner}/{repo}/hooks/{id}/deliveries`      | `webhooks`   |

+| POST   | `/api/v1/repos/{owner}/{repo}/hooks/{id}/deliveries/{delivery}/redeliver` | `webhooks` |

+

+Until these land, manage webhooks via the web UI under

+Repository → Settings → Webhooks.

+

+## Event types (canonical list)

+

+The events shippable today, by `X-Shithub-Event` header:

+

+- `push`

+- `pull_request` (actions: `opened`, `closed`, `merged`,

+  `reopened`, `edited`, `ready_for_review`, `converted_to_draft`,

+  `synchronize`)

+- `pull_request_review` (actions: `submitted`, `dismissed`)

+- `pull_request_review_comment`

+- `issues` (actions: `opened`, `closed`, `reopened`, `edited`,

+  `assigned`, `unassigned`, `labeled`, `unlabeled`)

+- `issue_comment`

+- `check_run` (actions: `created`, `completed`, `rerequested`)

+- `check_suite` (actions: `requested`, `completed`,

+  `rerequested`)

+- `star`

+- `fork`

+- `repository` (actions: `created`, `deleted`, `archived`,

+  `unarchived`, `renamed`, `transferred`, `publicized`,

+  `privatized`)

+- `ping` (test event you trigger manually)

+

+Each event's payload is documented per-type in the webhook detail

+page's "Recent deliveries" inspector — that's currently the

+authoritative reference until per-event documentation lands here.