Users (admin) API

Ask about this page View Markdown

Base URL: https://YOUR-SERVER/api. Send your API key in x-api-key where authentication is required. A key also needs the listed permission; your account's access rules still apply.

API guide · All endpoints · OpenAPI JSON

GET /admin/backup-devices — List backup device metadata across users
GET /admin/users/{id}/calendar-heatmap — Retrieve calendar heatmap activity
GET /admin/users/{id}/pin-code — Retrieve whether a user has a PIN
GET /admin/users/{id}/preferences — Retrieve user preferences
PUT /admin/users/{id}/preferences — Update user preferences
GET /admin/users/{id}/sessions — Retrieve user sessions
DELETE /admin/users/{id}/sessions/{sessionId} — `SessionService.delete` only checks `Permission.AuthDeviceDelete` over the caller's own sessions, so an administrator could never revoke a foreign session through it. This is the explicit, audited admin path the account detail's Security tab needs instead.
GET /admin/users/{id}/statistics — Retrieve user statistics

List backup device metadata across users

GET /api/admin/backup-devices

Administrative metadata only. No reconciliation digests or foreign asset access. quietForDays is elapsed whole days since reported successful backup, null when never reported.

Administrator access required.

Authentication: API key. Permission: adminUser.read.

Parameters

Name	Where	Required	Description
`limit`	query	No	integer
`offset`	query	No	integer

Parameter types, defaults and constraints

[
  {
    "name": "limit",
    "required": false,
    "in": "query",
    "schema": {
      "minimum": 1,
      "maximum": 200,
      "default": 100,
      "type": "integer"
    }
  },
  {
    "name": "offset",
    "required": false,
    "in": "query",
    "schema": {
      "minimum": 0,
      "maximum": 1000000,
      "default": 0,
      "type": "integer"
    }
  }
]

Responses

Field definitions: BackupDeviceListDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/BackupDeviceListDto"
        }
      }
    },
    "description": ""
  }
}

Retrieve calendar heatmap activity

GET /api/admin/users/{id}/calendar-heatmap

Retrieve activity counts for a specified period, in a calendar heatmap format.

Administrator access required.

Authentication: API key. Permission: adminUser.read.

Parameters

Name	Where	Required	Description
`from`	query	No	Start date in UTC
`id`	path	Yes	string
`to`	query	No	End date in UTC
`type`	query	No

Parameter types, defaults and constraints

Field definitions: CalendarHeatmapType

[
  {
    "name": "from",
    "required": false,
    "in": "query",
    "description": "Start date in UTC",
    "schema": {
      "format": "date",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
      "example": "2024-01-01",
      "type": "string"
    }
  },
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "to",
    "required": false,
    "in": "query",
    "description": "End date in UTC",
    "schema": {
      "format": "date",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
      "example": "2024-01-01",
      "type": "string"
    }
  },
  {
    "name": "type",
    "required": false,
    "in": "query",
    "schema": {
      "default": "Upload",
      "$ref": "#/components/schemas/CalendarHeatmapType"
    }
  }
]

Responses

Field definitions: CalendarHeatmapResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CalendarHeatmapResponseDto"
        }
      }
    },
    "description": ""
  }
}

Retrieve whether a user has a PIN

GET /api/admin/users/{id}/pin-code

Retrieve whether a specific user has a PIN code set, never the PIN itself.

Administrator access required.

Authentication: API key. Permission: adminUser.read.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: UserAdminPinCodeStateResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UserAdminPinCodeStateResponseDto"
        }
      }
    },
    "description": ""
  }
}

Retrieve user preferences

GET /api/admin/users/{id}/preferences

Retrieve the preferences of a specific user.

Administrator access required.

Authentication: API key. Permission: adminUser.read.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: UserPreferencesResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UserPreferencesResponseDto"
        }
      }
    },
    "description": ""
  }
}

Update user preferences

PUT /api/admin/users/{id}/preferences

Update the preferences of a specific user.

Deprecated. Avoid this operation in new integrations; use the replacement supported by your server release.

Administrator access required.

Authentication: API key. Permission: adminUser.update.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: UserPreferencesUpdateDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/UserPreferencesUpdateDto"
    }
  }
}

Responses

Field definitions: UserPreferencesResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UserPreferencesResponseDto"
        }
      }
    },
    "description": ""
  }
}

Retrieve user sessions

GET /api/admin/users/{id}/sessions

Retrieve all sessions for a specific user.

Administrator access required.

Authentication: API key. Permission: adminSession.read.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: SessionResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/SessionResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

`SessionService.delete` only checks `Permission.AuthDeviceDelete` over the caller's own sessions, so an administrator could never revoke a foreign session through it. This is the explicit, audited admin path the account detail's Security tab needs instead.

DELETE /api/admin/users/{id}/sessions/{sessionId}

Delete a specific session for a specific user, signing that device out.

Administrator access required.

Authentication: API key. Permission: adminSession.delete.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string
`sessionId`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "sessionId",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

{
  "204": {
    "description": ""
  }
}

Retrieve user statistics

GET /api/admin/users/{id}/statistics

Retrieve asset statistics for a specific user.

Administrator access required.

Authentication: API key. Permission: adminUser.read.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string
`isFavorite`	query	No	Filter by favorite status
`isTrashed`	query	No	Filter by trash status
`visibility`	query	No

Parameter types, defaults and constraints

Field definitions: AssetVisibility

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "isFavorite",
    "required": false,
    "in": "query",
    "description": "Filter by favorite status",
    "schema": {
      "type": "boolean"
    }
  },
  {
    "name": "isTrashed",
    "required": false,
    "in": "query",
    "description": "Filter by trash status",
    "schema": {
      "type": "boolean"
    }
  },
  {
    "name": "visibility",
    "required": false,
    "in": "query",
    "schema": {
      "$ref": "#/components/schemas/AssetVisibility"
    }
  }
]

Responses

Field definitions: AssetStatsResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AssetStatsResponseDto"
        }
      }
    },
    "description": ""
  }
}

Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.