​
Introduction

Chronologue uses RESTful API endpoints to connect the user-facing frontend (React chat and calendar UI) with the backend memory store, planner engine, and language model integration. These endpoints allow:
  • Chat-based task creation and agent planning
  • Memory trace storage and editing
  • Calendar generation and synchronization
  • Tempo-based personalization and reflection
  • Multi-agent orchestration via shared memory state
All endpoints return JSON and are organized by purpose below.

​
Authentication

All requests require a valid API key passed in the Authorization header. Header: Authorization: Bearer YOUR_API_KEY

​
Chat & Agent Interface

​
POST /chat/respond

Description: Process a natural language prompt and return structured response(s), traces, or planned actions. Request Body:
  • prompt: string
  • context: optional object including memory[] and calendar[]
Response:
Returns structured commands, proposed traces, or agent plan.

​
POST /chat/trace-summary

Description: Summarize relevant traces for token-efficient context injection. Request Body:
  • trace_ids: array of trace IDs
Response:
List of summarized memory snippets for grounding.

​
POST /chat/plan-preview

Description: Preview memory or calendar plan without committing it. Response:
Array of proposed memory traces or event objects with reasoning.

​
Memory Trace Management

​
POST /memory/push

Description: Save one or more new memory traces in Chronologue schema. Request Body:
  • traces: array of memory trace objects
Response:
List of saved trace UIDs with timestamps.

​
GET /memory/pull

Description: Retrieve memory by user_id, task_id, tempo_tag, or time range. Query Params:
  • user_id
  • type
  • start_time, end_time
Response:
List of matching memory trace objects.

​
PATCH /memory/edit

Description: Edit an existing trace by uid. Request Body:
  • uid: string
  • updates: object with new values
Response:
Updated trace object with version incremented.

​
GET /memory/history

Description: Return full revision history for a given trace. Query Params:
  • uid: string
Response:
List of prior versions and diffs.

​
POST /memory/search

Description: Search memory content using keywords, tags, or semantic embedding. Request Body:
  • query: string
Response:
List of matching trace summaries with confidence scores.

​
Calendar Event Integration

​
POST /calendar/create

Description: Add a calendar event (Chronologue .ics-compliant). Request Body:
  • title, scheduled_for, duration_minutes, task_id
Response:
Created event object with UID and ISO-8601 timestamps.

​
GET /calendar/events

Description: Retrieve upcoming or past events. Query Params:
  • start, end (ISO dates)
  • tag (optional)
Response:
Array of calendar event objects.

​
PATCH /calendar/edit

Description: Modify calendar entry fields. Request Body:
  • uid: string
  • updates: object
Response:
Modified event object.

​
DELETE /calendar/remove

Description: Delete a calendar event by UID. Query Param:
  • uid: string
Response:
Success message or error if not found.

​
Agent Planning & Execution

​
POST /agent/plan

Description: Generate structured plan from natural language prompt. Request Body:
  • prompt: string
  • context: memory and schedule
Response:
Ordered list of proposed actions with task_ids and temporal estimates.

​
POST /agent/execute

Description: Execute or simulate an agent task by ID. Request Body:
  • task_id: string
Response:
Execution log, result trace, or confirmation.

​
GET /agent/status

Description: Retrieve agent runtime status, plan queue, or diagnostics. Response:
Agent status summary.

​
Tempo & Preference Handling

​
GET /tempo/tags

Description: List available tempo tags for scheduling. Response:
Array of tag strings (e.g., @morning, 30min_block)

​
POST /tempo/adjust

Description: Update user or task-specific timing preferences. Request Body:
  • user_id, preferences
Response:
Updated preference profile.

​
GET /tempo/profile

Description: Get a user’s known tempo preferences. Query Param:
  • user_id: string
Response:
Profile with time ranges, tag mappings, and duration biases.

​
User & Session Management

​
POST /user/login

Description: Authenticate and return session token. Request Body:
  • email, password
Response:
JWT token or session object.

​
GET /user/profile

Description: Retrieve user-specific memory, tempo, and preference settings.

​
PATCH /user/update

Description: Update settings for a given user. Request Body:
  • user_id, updates
Response:
Modified user profile.

​
System Utilities

​
GET /health

Description: Check API status. Response:
200 OK

​
GET /version

Description: Return current Chronologue API version and build metadata.

​
POST /debug/trace-dump

Description: Developer tool for dumping memory snapshot for inspection. Response:
List of traces + metadata.