osu-api-glance

A local wrapper around the osu! api, intended for usage in glance (but theoretically universally usuable).

Examples for glance widgets can be found here.

Usage

1. Navigate to your docker-compose.yml
2. Clone this repository
3. Add the following to your docker-compose.yml containing glance:

osu-api-glance:
    build:
      context: ./osu-api-glance # path to the cloned repository
      dockerfile: Dockerfile
    ports:
      - 7270:8000 # 7270 is the outgoing port
    volumes:
      - ./osu-api-glance:/srv/root # path to the cloned repository
    environment:
      OSU_SESSION: # your "osu_session" cookie , must be updated once per month
      OSU_CSRF_TOKEN: # your "X-Csrf-Token" header, must be updated once per month
      API_KEY: changeme # an optional API key for preventing unauthorized access

Inside glance, you can access the API via http://osu-api-glance:8000. From the outside, the API can be accessed via the outgoing port (7270 by default).

If an API_KEY is specified in the docker-compose.yml, an Authorization header with value Basic <API_KEY> is required. Otherwise, 401 Unauthorized is returned.

GET /notifications

Serves all notifications ordered by date, with optional filters.

Query parameters
limit limits the amount of notifications returned
includes only displays the notifications with the specified name (comma-delimited)
excludes displays all but the notifications with the specified name (comma-delimited)

Example Response

{
    "notifications": [
      {
        "cover_url": "https://assets.ppy.sh/beatmaps/2426118/covers/card.jpg?1776694203",
        "created_at": "2026-04-28T02:26:30+00:00",
        "id": 897987799,
        "is_read": true,
        "name": "beatmapset_disqualify",
        "object_id": 2426118,
        "object_type": "beatmapset",
        "status": "beatmap status changed",
        "title": "\"Noah Fence\" has been disqualified",
        "url": "https://osu.ppy.sh/beatmapsets/2426118/discussion",
        "username": "Smoke"
      }
    ],
    "unread_count": 0
}

POST /notifications/mark-as-read

Marks a notification as read.

Example Body

{
    "id": 897987799,
    "name": "beatmapset_disqualify",
    "object_id": 2426118,
    "object_type": "beatmapset"
}