Hosts API

Host endpoints manage the authenticated Host's profile and settings. All endpoints require authentication.

Base: /api/host

GET /api/host/profile

Get the authenticated Host's profile.

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "host@example.com",
  "display_name": "John Doe",
  "status": "active",
  "setup_complete": true,
  "created_at": "2026-02-21T10:00:00Z",
  "updated_at": "2026-02-21T12:00:00Z"
}

Response Fields

Field	Type	Description
id	uuid	Unique identifier
email	string	User's email
display_name	string	Display name
status	string	Account status (pending_verification, active)
setup_complete	boolean	Whether setup wizard completed
created_at	timestamp	Account creation time
updated_at	timestamp	Last profile update

---

PUT /api/host/profile

Update the Host's profile.

Headers

Authorization: Bearer <access_token>

Request

{
  "display_name": "John D.",
  "email": "newemail@example.com"
}

Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "newemail@example.com",
  "display_name": "John D.",
  "status": "active",
  "setup_complete": true,
  "created_at": "2026-02-21T10:00:00Z",
  "updated_at": "2026-02-21T14:00:00Z"
}

Validation

Field	Required	Rules
display_name	No	1-100 characters
email	No	Valid email, unique

---

GET /api/host/settings

Get current liveness and threshold settings.

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "hcit_days": 30,
  "hcrt_hours": 48,
  "hcrac": 3,
  "survivor_threshold": 3,
  "preferred_connector_id": "550e8400-e29b-41d4-a716-446655440001",
  "calculated_activation_days": 34,
  "warnings": []
}

Response Fields

Field	Type	Description
hcit_days	integer	Check-in interval (7, 14, 30, 60, 90)
hcrt_hours	integer	Response time (24, 48, 72)
hcrac	integer	Retry attempts (1-5)
survivor_threshold	integer	Minimum survivors required
preferred_connector_id	uuid	Primary notification connector
calculated_activation_days	integer	Worst-case days to activation
warnings	array	Warnings about settings

Settings Warnings

Possible warnings:

• "Settings are too aggressive" — Less than 14 days to activation
• "Settings are too lenient" — More than 180 days to activation

---

PUT /api/host/settings

Update liveness and threshold settings.

Headers

Authorization: Bearer <access_token>

Request

{
  "hcit_days": 14,
  "hcrt_hours": 72,
  "hcrac": 2,
  "survivor_threshold": 2,
  "preferred_connector_id": "550e8400-e29b-41d4-a716-446655440001"
}

Response (200 OK)

{
  "hcit_days": 14,
  "hcrt_hours": 72,
  "hcrac": 2,
  "survivor_threshold": 2,
  "preferred_connector_id": "550e8400-e29b-41d4-a716-446655440001",
  "calculated_activation_days": 17,
  "warnings": []
}

Validation

Field	Required	Valid Values
hcit_days	No	7, 14, 30, 60, 90
hcrt_hours	No	24, 48, 72
hcrac	No	1, 2, 3, 4, 5
survivor_threshold	No	2 to current survivor count
preferred_connector_id	No	Valid connector ID

Errors

• 400 — Validation error
• 409 — Threshold exceeds survivor count

---

Rate Limits

Endpoint	Limit	Window
All /host/*	100 requests	1 minute

---

Example: Full Profile Update

curl -X PUT "https://api.example.com/api/host/profile" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "John Doe",
    "email": "john@example.com"
  }'

Example: Update Liveness Settings

curl -X PUT "https://api.example.com/api/host/settings" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hcit_days": 30,
    "hcrt_hours": 48,
    "hcrac": 3,
    "survivor_threshold": 2
  }'

---

Related Endpoints

• Authentication — Login/Register
• Liveness API — Check confirmation
• Survivors API — Manage survivors