Your sky over the API: GET /api/v1/user/sky, the dashboard backdrop's data for the Android app; 0.9.11 (refs andymccall/oxygenhub-android#23) 4dfa4599b3f7

## 0.9.11 (2026-10-28)

- **Your sky over the API (oxygenhub-android#23).** `GET /api/v1/user/sky` gives what the dashboard's backdrop draws: the caller's repositories and their pushes, proposal and issue events, releases and Flow runs of the last 30 days, so the Android app draws the same sky from the same data.

version = "0.9.11"

version = "0.9.11"

version = "0.9.11"

version = "0.9.11"

/// `GET /user/sky` (oxygenhub-android#23): Your sky's data, as the web

/// dashboard's backdrop reads it (docs/backgrounds.md §5): the caller's

/// repositories, newest-updated first, and their events of the last 30

/// days, newest first.

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct UserSky {

    /// The hub's clock (milliseconds), to age the events by.

    pub now: i64,

    /// `owner/name` of each repository.

    pub repos: Vec<String>,

    /// `[repo, kind, at_ms, n]`: an index into `repos`; kind 0 a push of

    /// `n` changes, 1 a proposal event, 2 an issue event, 3 a release, 4 a

    /// Flow run.

    pub events: Vec<[i64; 4]>,

}

        .route("/user/sky", get(user_sky))

/// `GET /user/sky` (oxygenhub-android#23): Your sky's data for the app,

/// what the web dashboard's backdrop draws: the repositories the caller

/// belongs to and may read, and their events of the last 30 days. Only the

/// database is read, never a repository's store.

async fn user_sky(State(app): State<Shared>, headers: HeaderMap) -> Result<Json<hub_api::UserSky>, ApiError> {

    let c = caller(&app, &headers).await?;

    let me = c.require("repo:read")?.clone();

    let member = db::accounts::visible_repo_ids(&app.db, me.id).await?;

    let mut mine = Vec::new();

    for r in db::repos::list(&app.db).await? {

        if member.contains(&r.id) && auth::roles::allows(auth::roles::role_for(&app.db, Some(&me), &r).await?, Access::Read) {

            mine.push(r);

        }

    }

    mine.sort_by_key(|r| std::cmp::Reverse(r.updated_ms));

    let ids: Vec<i64> = mine.iter().map(|r| r.id).collect();

    let now = db::now_ms();

    let since = now - crate::web::home::SKY_DAYS * 86_400_000;

    let events = db::activity::sky(&app.db, &ids, since, crate::web::home::SKY_EVENTS).await?;

    let events = events.iter().filter_map(|e| Some([ids.iter().position(|&id| id == e.repo_id)? as i64, e.kind, e.at_ms, e.n])).collect();

    Ok(Json(hub_api::UserSky { now, repos: mine.iter().map(|r| format!("{}/{}", r.owner, r.name)).collect(), events }))

}

pub(crate) const SKY_EVENTS: i64 = 1500;

pub(crate) const SKY_DAYS: i64 = 30;

    // Your sky for the app (oxygenhub-android#23): the dashboard's backdrop data.

    let (st, v) = api(app, "GET", "/api/v1/user/sky", Some(&andy_ro), None).await;

    assert_eq!(st, StatusCode::OK, "{v}");

    let demo = v["repos"].as_array().unwrap().iter().position(|r| r == "andy/demo").expect("andy's repository") as i64;

    let events = v["events"].as_array().unwrap();

    assert!(events.iter().any(|e| e[0] == demo && e[1] == 0), "a push: {v}");

    assert!(events.iter().any(|e| e[0] == demo && e[1] == 1), "a proposal event: {v}");

    assert!(events.iter().all(|e| e[2].as_i64().unwrap() <= v["now"].as_i64().unwrap()));

    assert_eq!(api(app, "GET", "/api/v1/user/sky", None, None).await.0, StatusCode::UNAUTHORIZED);

JSON under `/api/v1`, bearer tokens, `application/json`, RFC 7807 problem responses (an unknown route, or a known one with the wrong method, too), cursor pagination (`?after=`), ETags on cacheable resources, and rate limits per token. Resources mirror the pages: `/repos/{owner}/{name}`, `/bookmarks`, `/changes/{hash}`, `/tree/{ref}/{path}`, `/file/{ref}/{path}`, `/blame`, `/history/{ref}` (`?path=`, `?offset=&limit=`, or `?r=REVSET` for the changes a revset selects, evaluated under a two-second budget and answering 400 when it does not parse or goes past it; Oxygen's docs/revset_query_language.md), `/compare`, `/conflicts`, `/proposals` (`?state=open|draft|landed|closed|all`, open ones and drafts by default; a source bookmark may hold `/`, and `owner/name:bookmark` naming the repository itself is its own bookmark), `/proposals/{n}/comments|reviews|checks|files`, `PATCH /proposals/{n}` (the title and description, for its author or a maintainer, and `labels`, the whole set by name, for triage; what is not given stays), `POST /proposals/{n}/land` (repo:write: what the Land button does, `409` with the blockers when it cannot; a landed proposal keeps the changes it landed and reports `landed` with who, how (`web`, or `api (token NAME)`) and when, which its event, the audit log and the push record also say, adding when nobody approved), `/proposals/{n}/content/{base|head}/{path}` (a changed file's bytes in the target's state or the projected state, for editor diff views), `/issues` (creating an issue can set its labels, assignees and milestone; `PATCH /issues/{n}` edits the title and body for the author or triage, and replaces labels, assignees or the milestone for triage, recording each on the timeline; unknown names are refused before anything changes), `/labels` (`POST` creates or changes one, `DELETE /labels/{name}` removes it; triage), `/milestones` (`POST` creates one or changes the description and due date of the one with that title, `PATCH /milestones/{title}` changes title, description, due date or state; triage), `/releases` (`PATCH /releases/{tag}` changes the title, notes or prerelease flag, repo:write), `/tags` (`POST` creates one, repo:write; `DELETE /tags/{tag}` withdraws one, a maintainer, `409` while a release uses it; §9), `/trust`, `/pushes`, `/hooks`, `/checks`, `/user`, `/user/repos` (the caller's own, organisations' and collaborations, `?affiliation=&after=&limit=`, #302), `/user/orgs`, `/user/sky` (Your sky's data, the dashboard backdrop's: the caller's repositories and their events of the last 30 days as `[repo, kind, at_ms, n]`, for the Android app; oxygenhub-android#23), `/notifications` (the caller's inbox and unread count, each with its repository, reason, thread and label, #305; `/notifications/{id}/read` and `/notifications/read` mark read; scope `user:read`), `/users/{name}`, `/users/{name}/drops` and `/drops` (§4.5), `/orgs/{name}`, `/checks/{state}` (the checks on a state, named by its hash, by its heads joined with `+`, by the one head of a single-head state, or by a bookmark), `/checks/required` (`GET`, and `PUT` of the whole list by a repository admin: the checks a proposal needs, passed, to land), `/projects/{owner}` (list, create) and `/projects/{owner}/{n}` (the board as the caller may see it, `PATCH` for title, description, privacy and closing, and `owner` to transfer it to an owner the caller may make boards under (#125: it takes the next number there, and its old address redirects), `/cards` to list them by column or add a reference or note to a column named by id or name, `/cards/{id}` to move or remove one, `POST /cards/move` (#289: `{"from", "column", "except", "state", "dry_run"}`) to move a column's cards at once, but those `except` names (card ids or issue and proposal references) and, given `state`, only those whose issue or proposal is in one, all or none and audited once, answering what moved and what was kept; `POST /cards/archive` (#293: `{"from", "older_days", "except", "state", "dry_run"}`, the same selection and an age) to archive them, `GET /cards?archived=true` to list the archived ones (each with `archived_ms`) and `POST /cards/{id}/restore` to put one back; cards carry their `labels` and `assignees`; `repo:write` and the page's rights to change), `/coverage` and `/tests` (a bookmark's coverage and JUnit test reports from Flow jobs, newest first, `?bookmark=&limit=`), `POST /coverage` (repo:write, #136: `{"bookmark"}` or `{"change"}` and `content`, an LCOV, Cobertura or JaCoCo report measured off the hub, kept for that state as uploaded by the caller, shown "uploaded by NAME" wherever a run number would be, and setting no check; `oh coverage upload FILE`), `/coverage/{id}` (a report with its files) and `/tests/{id}` (a report with its cases, `?status=failed` for the failed and errored ones), `/flow/runs` (`GET`: runs newest first, `?before=N&limit=`; `POST {"bookmark"}` or `{"change"}`, repo:write: run a bookmark's current state, the default bookmark when none is named, or one change's state; with `"jobs": [NAME..]` only those jobs and what they depend on, each one a manual run starts, else `409` naming the ones it does (#130); `oh run start --job NAME`), `/flow/runs/{n}` (a run with its jobs), `/flow/runs/{n}/jobs/{job}/log` (`?after=seq&limit=`) and `/flow/runs/{n}/rerun` (repo:write: a finished run again), both answering `201 {"number", "url"}` or `409` with why nothing started, `/flow/runs/{n}/jobs/{job}/rerun` (repo:write, oxygenflow#31: that job of a finished run again, in the same run, with the jobs that depend on it; what it depends on keeps its result, so a flaky test reruns without its build; their logs, artifacts and reports go, their checks return to queued and the run is running again; `{"queued": N}`, or `409` while the run is live or for a job it lacks; RE-RUN THIS JOB on the run page, `oh run rerun N --job NAME`), `/flow/runs/{n}/cancel` (repo:write: a run still going ends as `cancelled`, its running jobs stopped when their runner next reports; `409` when it had already ended; a push to a bookmark cancels the push runs of it still going), `/search`. A change's author carries the account its key is linked to, or `null` and a `note` saying the key is not linked and where its owner links it; `via` names the delegate (an agent) that signed for the author when one did, with the delegation's scope and expiry and whether it has since been revoked, and the pages show the same as an `agent` badge, a `via` row under the author on the change page, and a count under the author in Contributors (the change page shows a "key not linked" tag, with a link to Settings → Keys for signed-in viewers). Shapes reuse `oxy --json` shapes wherever one exists (change, status, blame, diff) so tools written against the CLI work against the hub. `crates/hub-api` holds the types with `serde` derives and is what the runner and the VS Code extension will link.