Contextberg Local API

Contextberg Local API is a locally running HTTP server. It provides endpoints accessible from external tools like Cursor and Claude Desktop.

Base URL

http://localhost:18080

Authentication

Not required

CORS

Supported

Quick Start

With Contextberg running, execute the following commands to verify API connection.

Example

# 1. Health check
curl http://localhost:18080/api/health
# => { "status": "ok" }

# 2. Get today's summary
curl http://localhost:18080/api/summary/today

# 3. Get daily report
curl "http://localhost:18080/api/daily-report?include=activities,keystrokes"

Daily Reportv3

GET/api/daily-report

Get comprehensive daily activity report. Includes activities, keystrokes, screenshots, AI reports, and all daily activity data in one request.

Parameters

datestringoptionalTarget date (YYYY-MM-DD format). Default is today.

app_filterstringoptionalFilter by application name.

includestringoptionalSections to include (comma-separated)

include options

activitieskeystrokesclipboardbrowserreports

Response

{
  "date": "2025-12-31",
  "activities": {
    "totalWorkSeconds": 28800,
    "totalWorkFormatted": "8h 0m",
    "appSummary": [...]
  },
  "keystrokes": {
    "count": 150,
    "inputs": [...]
  }
}

Weekly Reportv3

GET/api/weekly-report

Get weekly summary and trends. Includes daily work hours, top applications, and trend analysis.

Parameters

end_datestringoptionalEnd date (YYYY-MM-DD format). Default is today.

daysintegeroptionalNumber of days. Default is 7.

includestringoptionalSections to include

Response

{
  "period": {
    "start": "2025-12-24",
    "end": "2025-12-30",
    "days": 7
  },
  "totalWorkFormatted": "40h 0m"
}

Screenshotsv3

GET/api/screenshots

Get screenshots with Base64 image data. Includes OCR text. Smart selection algorithm automatically selects important screenshots.

Parameters

datestringoptionalTarget date (YYYY-MM-DD format).

limitintegeroptionalMaximum number. Default is 15.

Response

{
  "date": "2025-12-31",
  "count": 10,
  "screenshots": [...]
}

Today Summary

GET/api/summary/today

Get today's summary. Lightweight response for quick overview.

Response

{
  "date": "2025-12-31",
  "totalWorkFormatted": "8h 0m"
}

Week Summary

GET/api/summary/week

Get weekly summary. Lightweight response for week overview.

Response

{
  "period": { ... },
  "totalWorkFormatted": "40h 0m"
}

Activities

GET/api/activities

Get activity list. Application usage history in chronological order.

Parameters

daysintegeroptionalNumber of days. Default is 1.

limitintegeroptionalMaximum count. Default is 100.

Response

{
  "days": 1,
  "activities": [...]
}

Keystrokes

GET/api/keystrokes

Get keystroke history. Records with empty input text are skipped.

Parameters

daysintegeroptionalNumber of days. Default is 1.

limitintegeroptionalMaximum count. Default is 100.

Response

{
  "days": 1,
  "inputs": [...]
}

Browser History

GET/api/browser

Get browser history. Domain-based aggregation mode available.

Parameters

daysintegeroptionalNumber of days. Default is 1.

limitintegeroptionalMaximum count. Default is 50.

Response

{
  "mode": "detailed",
  "visits": [...]
}

Clipboard

GET/api/clipboard

Get clipboard history. Text is truncated to first 100 characters (privacy protection).

Parameters

daysintegeroptionalNumber of days. Default is 1.

limitintegeroptionalMaximum count. Default is 20.

Response

{
  "days": 1,
  "clipboardHistory": [...]
}

Timeline

GET/api/timeline

Get timeline view. Integrated activities in chronological order.

Parameters

daysintegeroptionalNumber of days. Default is 1.

granularityintegeroptionalTime slot granularity (minutes). Default is 30.

Response

{
  "period": { ... },
  "timeline": [...]
}

Health Check

GET/api/health

API server health check.

Response

{
  "status": "ok",
  "service": "Contextberg Local API"
}

Export

GET/api/export

Export data in JSON or Markdown format.

Parameters

daysintegeroptionalNumber of days. Default is 7.

formatstringoptionalOutput format. json or markdown.

Response

// JSON format
curl "http://localhost:18080/api/export?format=json"

// Markdown format
curl "http://localhost:18080/api/export?format=markdown"

HTTP Status Codes

Code	Description
`200`	Success
`204`	No Content (OPTIONS request)
`404`	Endpoint does not exist
`500`	Server error