headquarter/docs/api/users.md

Users API

User profile and settings management.

Authentication

All endpoints require authentication (session cookie).

---

GET /users/me

Description: Get current user profile.

Response

Success (200 OK)

{
  "id": "uuid",
  "email": "user@example.com",
  "name": "User Name",
  "avatar_url": "https://...",
  "authentik_id": "authentik-uuid",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

---

PUT /users/me

Description: Update user profile.

Request

Request Body

{
  "name": "New Name",
  "email": "newemail@example.com"
}

Field	Type	Required	Description
name	string	No	New display name
email	string	No	New email address

Response

Success (200 OK)

{
  "id": "uuid",
  "email": "newemail@example.com",
  "name": "New Name",
  "avatar_url": "https://...",
  "updated_at": "2024-01-02T00:00:00Z"
}

---

POST /users/me/avatar

Description: Upload avatar image.

Request

Request Body

Multipart form data with file field.

Requirements:

• Format: PNG or JPEG
• Max size: 2MB

Response

Success (200 OK)

{
  "avatar_url": "/uploads/avatars/uuid.png"
}

Error (400 Bad Request)

{
  "detail": "Invalid file format. Only PNG and JPEG are allowed."
}

---

GET /users/me/config

Description: Get user settings.

Response

Success (200 OK)

{
  "id": "uuid",
  "user_id": "uuid",
  "config": {
    "theme": "dark",
    "git_identity": {
      "name": "User Name",
      "email": "user@example.com"
    },
    "default_editor": "code-server"
  }
}

---

PATCH /users/me/config

Description: Update user settings.

Request

Request Body

{
  "theme": "light",
  "git_identity": {
    "name": "New Name",
    "email": "new@example.com"
  }
}

Field	Type	Required	Description
theme	string	No	"system", "light", or "dark"
git_identity	object	No	{name, email}
default_editor	string	No	Preferred editor

Response

Success (200 OK)

{
  "id": "uuid",
  "user_id": "uuid",
  "config": {
    "theme": "light",
    "git_identity": {
      "name": "New Name",
      "email": "new@example.com"
    }
  }
}