openapi: 3.1.0
info:
  title: systemd-logind (org.freedesktop.login1)
  version: '1.0'
  summary: D-Bus API of systemd-logind modeled as REST operations.
  description: |
    Documentation/contract artifact modeling the `org.freedesktop.login1` D-Bus interface set
    (system bus). systemd-logind tracks user logins, seats, sessions, and inhibitor locks; gates
    power/reboot/sleep operations; manages ACLs for hot-pluggable devices; and exposes inhibitor
    locks so applications can delay shutdown or idle handling.

    Bus name: `org.freedesktop.login1`. Root object path: `/org/freedesktop/login1`.
  license: { name: LGPL-2.1-or-later, url: https://github.com/systemd/systemd/blob/main/LICENSES/LGPL-2.1-or-later.txt }
servers:
- url: dbus://system/org.freedesktop.login1
tags:
- name: Sessions
- name: Users
- name: Seats
- name: Power
- name: Inhibitors
paths:
  /sessions:
    get:
      tags: [Sessions]
      operationId: ListSessions
      summary: List All Active Sessions
      description: Mirrors `ListSessions()`. Returns an array of (session id, uid, user name, seat id, object path).
      responses: { '200': { description: Array of sessions., content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/Session' } } } } } }
  /sessions/{id}:
    parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
    get:
      tags: [Sessions]
      operationId: GetSession
      summary: Get A Session By ID
      description: Mirrors `GetSession(id)`. Returns the session object path.
      responses: { '200': { description: Session object path., content: { application/json: { schema: { type: object, properties: { path: { type: string } } } } } } }
  /sessions/{id}/terminate:
    parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
    post:
      tags: [Sessions]
      operationId: TerminateSession
      summary: Terminate A Session
      description: Mirrors `TerminateSession(id)`. Kills all processes in the session's cgroup.
      responses: { '204': { description: Session terminated. } }
  /sessions/{id}/lock:
    parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
    post:
      tags: [Sessions]
      operationId: LockSession
      summary: Request Session Lock
      description: Mirrors `LockSession(id)`. Asks the session's lock UI to engage.
      responses: { '204': { description: Lock requested. } }
  /sessions/{id}/unlock:
    parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
    post:
      tags: [Sessions]
      operationId: UnlockSession
      summary: Request Session Unlock
      description: Mirrors `UnlockSession(id)`.
      responses: { '204': { description: Unlock requested. } }
  /users:
    get:
      tags: [Users]
      operationId: ListUsers
      summary: List Logged-In Users
      description: Mirrors `ListUsers()`.
      responses: { '200': { description: Array of (uid, name, object path)., content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/User' } } } } } }
  /users/{uid}:
    parameters: [{ name: uid, in: path, required: true, schema: { type: integer } }]
    get:
      tags: [Users]
      operationId: GetUser
      summary: Get A User By UID
      description: Mirrors `GetUser(uid)`.
      responses: { '200': { description: User object path., content: { application/json: { schema: { type: object, properties: { path: { type: string } } } } } } }
  /users/{uid}/terminate:
    parameters: [{ name: uid, in: path, required: true, schema: { type: integer } }]
    post:
      tags: [Users]
      operationId: TerminateUser
      summary: Terminate A User's Sessions
      description: Mirrors `TerminateUser(uid)`.
      responses: { '204': { description: Terminated. } }
  /seats:
    get:
      tags: [Seats]
      operationId: ListSeats
      summary: List Seats
      description: Mirrors `ListSeats()`.
      responses: { '200': { description: Array of (seat id, object path)., content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/Seat' } } } } } }
  /power/poweroff:
    post:
      tags: [Power]
      operationId: PowerOff
      summary: Power Off The System
      description: Mirrors `PowerOff(interactive)`.
      requestBody: { content: { application/json: { schema: { type: object, properties: { interactive: { type: boolean } } } } } }
      responses: { '204': { description: Shutdown initiated. } }
  /power/reboot:
    post:
      tags: [Power]
      operationId: Reboot
      summary: Reboot The System
      description: Mirrors `Reboot(interactive)`.
      requestBody: { content: { application/json: { schema: { type: object, properties: { interactive: { type: boolean } } } } } }
      responses: { '204': { description: Reboot initiated. } }
  /power/suspend:
    post:
      tags: [Power]
      operationId: Suspend
      summary: Suspend The System
      description: Mirrors `Suspend(interactive)`.
      requestBody: { content: { application/json: { schema: { type: object, properties: { interactive: { type: boolean } } } } } }
      responses: { '204': { description: Suspend initiated. } }
  /power/hibernate:
    post:
      tags: [Power]
      operationId: Hibernate
      summary: Hibernate The System
      description: Mirrors `Hibernate(interactive)`.
      requestBody: { content: { application/json: { schema: { type: object, properties: { interactive: { type: boolean } } } } } }
      responses: { '204': { description: Hibernate initiated. } }
  /power/hybrid-sleep:
    post:
      tags: [Power]
      operationId: HybridSleep
      summary: Hybrid Sleep The System
      description: Mirrors `HybridSleep(interactive)`.
      responses: { '204': { description: HybridSleep initiated. } }
  /inhibitors:
    get:
      tags: [Inhibitors]
      operationId: ListInhibitors
      summary: List All Inhibitor Locks
      description: Mirrors `ListInhibitors()`.
      responses: { '200': { description: Array of inhibitor records., content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/Inhibitor' } } } } } }
    post:
      tags: [Inhibitors]
      operationId: Inhibit
      summary: Acquire An Inhibitor Lock
      description: Mirrors `Inhibit(what, who, why, mode)`. Returns an FD representing the lock.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [what, who, why, mode]
              properties:
                what:
                  type: string
                  description: "Colon-separated list of shutdown, sleep, idle, handle-power-key, handle-suspend-key, handle-hibernate-key, handle-lid-switch."
                who: { type: string }
                why: { type: string }
                mode: { type: string, enum: [block, delay] }
      responses: { '200': { description: Lock acquired (FD returned over D-Bus)., content: { application/json: { schema: { type: object, properties: { fd: { type: integer } } } } } } }
components:
  schemas:
    Session:
      type: object
      properties:
        session_id: { type: string }
        uid: { type: integer }
        user_name: { type: string }
        seat_id: { type: string }
        object_path: { type: string }
    User:
      type: object
      properties:
        uid: { type: integer }
        name: { type: string }
        object_path: { type: string }
    Seat:
      type: object
      properties:
        seat_id: { type: string }
        object_path: { type: string }
    Inhibitor:
      type: object
      properties:
        what: { type: string }
        who: { type: string }
        why: { type: string }
        mode: { type: string, enum: [block, delay] }
        uid: { type: integer }
        pid: { type: integer }