# Log my Care Open API

Read-only API for accessing Log my Care data. Authenticate by exchanging your API key for a JWT token via <code>POST /openapi/auth/token/exchange</code>, then include the token in the <code>Authorization: Bearer</code> header.

<h2>Authentication</h2>

<p><strong>Token Exchange (Required)</strong>: Exchange the API key for a short-lived JWT token (15 minutes) using <code>POST /openapi/auth/token/exchange</code>. This provides enhanced security by minimizing API key exposure.</p>

<p>All authenticated endpoints require a valid JWT token in the <code>Authorization: Bearer</code> header.</p>

<h2>Available Endpoints</h2>

<h3>Health & Status</h3>
<ul>
  <li><code>GET /health</code> - System health check (no authentication required)</li>
  <li><code>GET /openapi/health</code> - Alternative health check path (legacy compatibility)</li>
</ul>

<h3>Residents</h3>
<ul>
  <li><code>GET /openapi/api/residents</code> - List all residents with filtering and pagination</li>
  <li><code>GET /openapi/api/residents/:id</code> - Get specific resident by ID</li>
  <li>Filters: <code>homeId</code>, <code>residentId</code>, <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
</ul>

<h3>Care Plans</h3>
<ul>
  <li><code>GET /openapi/api/careplans</code> - List all care plans with filtering</li>
  <li><code>GET /openapi/api/careplans/:id</code> - Get specific care plan by ID</li>
  <li>Filters: <code>homeId</code>, <code>residentId</code>, <code>carePlanId</code>, <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
</ul>

<h3>Goals</h3>
<ul>
  <li><code>GET /openapi/api/goals</code> - List all goals with filtering</li>
  <li><code>GET /openapi/api/goals/:id</code> - Get specific goal by ID</li>
  <li>Filters: <code>homeId</code>, <code>residentId</code>, <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
</ul>

<h3>Incident Reports</h3>
<ul>
  <li><code>GET /openapi/api/incident-reports</code> - List all incident reports</li>
  <li><code>GET /openapi/api/incident-reports/:id</code> - Get specific incident report by ID</li>
  <li>Filters: <code>homeId</code>, <code>residentId</code>, <code>severity</code>, <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
</ul>

<h3>Risk Assessments</h3>
<ul>
  <li><code>GET /openapi/api/risk-assessments</code> - List all risk assessments</li>
  <li><code>GET /openapi/api/risk-assessments/:id</code> - Get specific risk assessment by ID</li>
  <li>Filters: <code>homeId</code>, <code>residentId</code>, <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
</ul>

<h3>Homes</h3>
<ul>
  <li><code>GET /openapi/api/homes</code> - List all care homes</li>
  <li><code>GET /openapi/api/homes/:id</code> - Get specific home by ID</li>
  <li>Filters: <code>page</code>, <code>limit</code></li>
</ul>

<h3>Users</h3>
<ul>
  <li><code>GET /openapi/api/users</code> - List all users</li>
  <li><code>GET /openapi/api/users/:id</code> - Get specific user by ID</li>
  <li>Filters: <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
</ul>

<h3>Logs</h3>
<ul>
  <li><code>GET /openapi/api/logs</code> - List all daily care logs</li>
  <li><code>GET /openapi/api/logs/:id</code> - Get specific log by ID</li>
  <li>Filters: <code>homeId</code>, <code>residentId</code>, <code>categoryId</code>, <code>itemId</code>, <code>loggedById</code>, <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
</ul>

<h3>Log Categories</h3>
<ul>
  <li><code>GET /openapi/api/logcategories</code> - List all log categories (no authentication required)</li>
  <li><code>GET /openapi/api/logcategories/:id</code> - Get specific log category by ID (no authentication required)</li>
  <li>Filters: <code>page</code>, <code>limit</code></li>
</ul>

<h3>Log Category Items</h3>
<ul>
  <li><code>GET /openapi/api/logcategoryitems</code> - List all log category items (no authentication required)</li>
  <li><code>GET /openapi/api/logcategoryitems/:id</code> - Get specific log category item by ID (no authentication required)</li>
  <li>Filters: <code>page</code>, <code>limit</code></li>
</ul>

<h3>Documents</h3>
<ul>
  <li><code>GET /openapi/api/documents</code> - List all resident documents</li>
  <li><code>GET /openapi/api/documents/:id</code> - Get specific document by ID</li>
  <li>Filters: <code>homeId</code>, <code>residentId</code>, <code>categoryId</code>, <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
</ul>

<h3>Home Documents</h3>
<ul>
  <li><code>GET /openapi/api/home-documents</code> - List all home-scoped documents</li>
  <li><code>GET /openapi/api/home-documents/:id</code> - Get specific home document by ID</li>
  <li>Filters: <code>homeId</code>, <code>categoryId</code>, <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
</ul>

<h2>Common Features</h2>

<p><strong>Pagination</strong>: All list endpoints support <code>page</code> (default: 1) and <code>limit</code> (default: 10, max: 100) parameters.</p>

<p><strong>Date Filtering</strong>: Many endpoints support <code>startDate</code>, <code>endDate</code>, and <code>dateField</code> parameters for filtering by date ranges.</p>

<p><strong>Rate limits</strong>: 100 requests/minute per IP (unauthenticated), 1,000 requests/minute with JWT token authentication.</p>

<p><strong>Security</strong>: All requests logged, input validated, parameterised queries, rate limiting enforced.</p>

Version: 1.0.0

## Servers

API Server
```
https://data.logmycare.co.uk/openapi
```

## Security

### Bearer

JWT token obtained from token exchange endpoint

Type: http
Scheme: bearer
Bearer Format: JWT

## Download OpenAPI description

[Log my Care Open API](https://apidocs.logmycare.co.uk/_bundle/docs/openapi/@v1.0.0/index.yaml)

## health

Health check and system status

### Health check

 - [GET /health](https://apidocs.logmycare.co.uk/docs/openapi/health/gethealth.md): Health check endpoint that returns the application status, uptime, and version information.
This endpoint is used by load balancers and monitoring systems.
Note: This endpoint does not require authentication.

### getHealthLegacy

 - [GET /openapi/health](https://apidocs.logmycare.co.uk/docs/openapi/health/gethealthlegacy.md)

## token-exchange

API key authentication

### Exchange API key for short-lived access token

 - [POST /auth/token/exchange](https://apidocs.logmycare.co.uk/docs/openapi/token-exchange/exchangetoken.md): Exchange a long-lived API key for a short-lived JWT access token (15 minutes).
This provides enhanced security by minimizing API key exposure.

Permissions and Scope:

  All permissions, scopes, and home access are automatically determined by the API key
  No need to specify permissions in the request body
  The generated token will have all permissions associated with the API key


Rate Limits:

  Production: 10/min, 100/hour, 1000/day per API key
  Test/Development: 30/min, 100/hour, 500/day per API key


Security Features:

  Tokens expire automatically after 15 minutes
  IP-based monitoring and abuse detection
  Comprehensive audit logging


Usage Pattern:

  Exchange API key for access token at secure endpoint
  Use access token for API calls (never use API key directly)
  Re-exchange when token expires (every 15 minutes)


This follows OAuth 2.0 Token Exchange (RFC 8693) patterns.

## Modules / Residents

Resident records

### Get residents

 - [GET /api/residents](https://apidocs.logmycare.co.uk/docs/openapi/modules-residents/getresidents.md): Retrieves residents with personal details, medical history, room location, and care preferences.
Filters:

  homeId - Filter by specific care home
  residentId - Filter by specific resident
  startDate, endDate - Date range filtering
  dateField - Date field to filter on (e.g., createdOn, admissionDate)
  page, limit - Pagination controls (default: page=1, limit=10, max=100)

### Create resident

 - [POST /api/residents](https://apidocs.logmycare.co.uk/docs/openapi/modules-residents/createresident.md)

### Get resident by ID

 - [GET /api/residents/{id}](https://apidocs.logmycare.co.uk/docs/openapi/modules-residents/getresidentbyid.md): Retrieves complete resident information including medical history, allergies, GP details, care preferences, and room location.

### Update resident

 - [PUT /api/residents/{id}](https://apidocs.logmycare.co.uk/docs/openapi/modules-residents/updateresident.md)

## Modules / Users

User records

### Get users

 - [GET /api/users](https://apidocs.logmycare.co.uk/docs/openapi/modules-users/getusers.md): Retrieves users with their roles, permissions, and homeIds. Password fields are excluded for security.
Filters:

  homeId - Filter by specific care home
  startDate, endDate - Date range filtering
  dateField - Date field to filter on (default: createdOn)
  page, limit - Pagination controls

### Create user

 - [POST /api/users](https://apidocs.logmycare.co.uk/docs/openapi/modules-users/createuser.md)

### Get user by ID

 - [GET /api/users/{id}](https://apidocs.logmycare.co.uk/docs/openapi/modules-users/getuserbyid.md): Retrieves a complete user profile including roles, permissions, homeIds, and employment details. Password fields are excluded for security.

### Update user

 - [PUT /api/users/{id}](https://apidocs.logmycare.co.uk/docs/openapi/modules-users/updateuser.md)

## Modules / Care Plans

Care plan records

### Get care plans

 - [GET /api/careplans](https://apidocs.logmycare.co.uk/docs/openapi/modules-care-plans/getcareplans.md): Retrieves care plans with goals, assessments, documents, and tracking information.
Filters:

  homeId - Filter by specific care home
  residentId - Filter by specific resident
  carePlanId - Filter by care plan ID
  startDate, endDate - Date range filtering
  dateField - Date field to filter on (default: createdOn)
  page, limit - Pagination controls

### Get care plan by ID

 - [GET /api/careplans/{id}](https://apidocs.logmycare.co.uk/docs/openapi/modules-care-plans/getcareplanbyid.md): Retrieves a complete care plan including goals, assessments, documents, risk assessments, and review history.

## Modules / Homes

Care home records

### Get homes

 - [GET /api/homes](https://apidocs.logmycare.co.uk/docs/openapi/modules-homes/gethomes.md): Retrieves care homes with facility details, CQC registration, address, capacity, and regulator information.
Filters:

  page, limit - Pagination controls

### Get home by ID

 - [GET /api/homes/{id}](https://apidocs.logmycare.co.uk/docs/openapi/modules-homes/gethomebyid.md): Retrieves complete care home information including CQC registration, address, bed capacity, home group, and regulator details.

## Modules / Incident Reports

Incident report records

### Get incident reports

 - [GET /api/incident-reports](https://apidocs.logmycare.co.uk/docs/openapi/modules-incident-reports/getincidentreports.md): Retrieves incident reports with severity, status, case details, and investigation notes.
Filters:

  homeId - Filter by specific care home
  residentId - Filter by specific resident
  severity - Filter by severity level (1=lowest, 5=highest)
  startDate, endDate - Date range filtering
  dateField - Date field to filter on (created_on, closed_on, reviewed_on, or ingested_on)
  page, limit - Pagination controls

### Get incident report by ID

 - [GET /api/incident-reports/{id}](https://apidocs.logmycare.co.uk/docs/openapi/modules-incident-reports/getincidentreportbyid.md): Retrieves complete incident details including log, case information, witnesses, actions taken, and closure notes.

## Modules / Goals

Goal records

### Get goals

 - [GET /api/goals](https://apidocs.logmycare.co.uk/docs/openapi/modules-goals/getgoals.md): Retrieves care goals with objectives, progress tracking, action plans, success measurements, and review history.
Filters:

  homeId - Filter by specific care home
  residentId - Filter by specific resident
  startDate, endDate - Date range filtering
  page, limit - Pagination controls

### Get goal by ID

 - [GET /api/goals/{id}](https://apidocs.logmycare.co.uk/docs/openapi/modules-goals/getgoalbyid.md): Retrieves complete goal details including objectives, progress history, action plans, logs, and success measurements.

## Modules / Risk Assessments

Risk assessment records

### Get risk assessments

 - [GET /api/risk-assessments](https://apidocs.logmycare.co.uk/docs/openapi/modules-risk-assessments/getriskassessments.md): Retrieves risk assessments with safety evaluations, hazard identification, risk scores, and mitigation strategies.
Filters:

  homeId - Filter by specific care home
  residentId - Filter by specific resident
  startDate, endDate - Date range filtering
  page, limit - Pagination controls

### Get risk assessment by ID

 - [GET /api/risk-assessments/{id}](https://apidocs.logmycare.co.uk/docs/openapi/modules-risk-assessments/getriskassessmentbyid.md): Retrieves complete risk assessment details including form data, risk scores, review history, and assessor information.

## Modules / Logs

Daily care log records

### Get logs (daily care notes)

 - [GET /api/logs](https://apidocs.logmycare.co.uk/docs/openapi/modules-logs/getlogs.md): Retrieves logs (daily care notes) logged by staff members about residents' care, activities, and observations.
Filters:

  homeId - Filter by specific care home
  residentId - Filter by specific resident
  categoryId - Filter by log category (e.g., Meals & Nutrition)
  itemId - Filter by log category item (e.g., Breakfast)
  loggedById - Filter by user who logged the entry
  startDate, endDate - Date range filtering
  dateField - Date field to filter on (default: timeLogged)
  page, limit - Pagination controls (default: page=1, limit=10, max=100)

Note: Deleted logs are automatically excluded from results.

### Get log by ID

 - [GET /api/logs/{id}](https://apidocs.logmycare.co.uk/docs/openapi/modules-logs/getlogbyid.md): Retrieves complete log information including populated references for home, resident, loggedBy, editedBy, category, and item.
Logs represent daily care notes and observations logged by staff members.

## Modules / Log Categories

Log category records

### Get log categories

 - [GET /api/logcategories](https://apidocs.logmycare.co.uk/docs/openapi/modules-log-categories/getlogcategories.md): Retrieves log categories used to classify daily care notes and observations.
Examples: Meals & Nutrition, Personal Care, Activities, Health & Wellbeing, Medication
Filters:

  page, limit - Pagination controls (default: page=1, limit=10, max=100)

Note: This endpoint does not require authentication. Log categories are public reference data.

### Get log category by ID

 - [GET /api/logcategories/{id}](https://apidocs.logmycare.co.uk/docs/openapi/modules-log-categories/getlogcategorybyid.md): Retrieves complete log category information including name, color, itemId, and custom/global status.
Log categories are used to organize and classify daily care logs.
Note: This endpoint does not require authentication.

## Modules / Log Category Items

Log category item records

### Get log category items

 - [GET /api/logcategoryitems](https://apidocs.logmycare.co.uk/docs/openapi/modules-log-category-items/getlogcategoryitems.md): Retrieves log category items representing specific activities or observations within a log category.
Examples: Breakfast (under Meals & Nutrition), Shower (under Personal Care), Walk in Garden (under Activities)
Filters:

  page, limit - Pagination controls (default: page=1, limit=10, max=100)

Note: This endpoint does not require authentication. Items are sorted by order for proper UI display.

### Get log category item by ID

 - [GET /api/logcategoryitems/{id}](https://apidocs.logmycare.co.uk/docs/openapi/modules-log-category-items/getlogcategoryitembyid.md): Retrieves complete log category item information including name, category reference, order, and visibility settings.
Log category items represent specific activities or observations that can be logged by staff members.
Note: This endpoint does not require authentication.

## Modules / Documents

Resident document records

### Get documents (resident documents)

 - [GET /api/documents](https://apidocs.logmycare.co.uk/docs/openapi/modules-documents/getdocuments.md): Retrieves resident-specific documents including medical records, assessments, care plans, and other resident documentation.
Filters:

  homeId - Filter by specific care home
  residentId - Filter by specific resident
  categoryId - Filter by document category
  startDate, endDate - Date range filtering
  dateField - Date field to filter on (default: createdAt)
  page, limit - Pagination controls (default: page=1, limit=10, max=100)

### Get document by ID

 - [GET /api/documents/{id}](https://apidocs.logmycare.co.uk/docs/openapi/modules-documents/getdocumentbyid.md): Retrieves complete document information including file details, category, resident, and home references.
Documents represent files uploaded for specific residents, including PDFs and other file types.

## Modules / Home Documents

Home-scoped document records

### Get home documents (home-scoped documents)

 - [GET /api/home-documents](https://apidocs.logmycare.co.uk/docs/openapi/modules-home-documents/gethomedocuments.md): Retrieves home-scoped documents including policies, procedures, licenses, training materials, and other home-level documentation.
Filters:

  homeId - Filter by specific care home
  categoryId - Filter by home document category
  startDate, endDate - Date range filtering
  dateField - Date field to filter on (default: createdAt)
  page, limit - Pagination controls (default: page=1, limit=10, max=100)

### Get home document by ID

 - [GET /api/home-documents/{id}](https://apidocs.logmycare.co.uk/docs/openapi/modules-home-documents/gethomedocumentbyid.md): Retrieves complete home document information including file details, category, and home references.
Home documents are scoped to care homes rather than individual residents, including policies, procedures, and licenses.

## Modules / Devices

Device records

### Get devices

 - [GET /api/devices](https://apidocs.logmycare.co.uk/docs/openapi/modules-devices/getdevices.md): Retrieves devices (tablets, phones, laptops) registered to care homes for logging activities.
All ObjectId reference fields are populated one level deep with { id, name }.
The homes array in the response is filtered to only include entries for homes the API key has access to.
Filters:

  type - Filter by device type (tablet, phone, laptop)
  deviceStatus - Filter by home assignment status (pending, approved, blocked)
  startDate, endDate - Date range filtering on createdOn
  page, limit - Pagination controls (default: page=1, limit=10, max=100)

### Get device by ID

 - [GET /api/devices/{id}](https://apidocs.logmycare.co.uk/docs/openapi/modules-devices/getdevicebyid.md): Retrieves complete device information including populated user references, home assignments with status, and audit fields.
The homes array is filtered to only include entries for homes the API key has access to. FCM (push notification) fields are excluded from the response.