1

WIKI_API_CONTRACT

stan44 edited this page 2026-02-23 20:19:14 -06:00

Table of Contents

• API and Sidecar Contract
• HTTP Surface (Locked)
• Envelope
• Action Map
• DTO Notes (C#)

API and Sidecar Contract

This page documents the canonical transport contract used by the C# backend.

HTTP Surface (Locked)

• POST /api/command
• GET /health
• GET /healthz

No template/demo endpoints are part of parity mode.

Envelope

Request (POST /api/command):

{
  "action": "entries.list",
  "id": "optional-guid",
  "payload": {},
  "correlationId": "optional-client-correlation-id"
}

Success response:

{
  "ok": true,
  "data": {}
}

Failure response:

{
  "ok": false,
  "error": "Missing or invalid payload"
}

Action Map

fragments.*

• fragments.list -> no payload
• fragments.get -> id (guid)
• fragments.create -> payload: { type, description, time?, tags? }
• fragments.update -> id (guid) + payload: { type?, description?, time?, tags? }
• fragments.delete -> id (guid)
• fragments.search -> optional top-level type, tag

entries.*

• entries.list -> payload: { dataDirectory? }
• entries.load -> payload: { filePath }
• entries.save -> payload: { fileName, content, dataDirectory? }

search.*

• search.entries -> payload: { dataDirectory, query?, section?, startDate?, endDate?, tags?, types?, checked?, unchecked? }

vault.*

• vault.initialize -> payload: { password, vaultDirectory }
• vault.load_all -> payload: { password, vaultDirectory, dataDirectory }
• vault.save_current_month -> payload: { password, vaultDirectory, dataDirectory, nowUtc? }
• vault.rebuild_all -> payload: { password, vaultDirectory, dataDirectory }
• vault.clear_data_directory -> payload: { dataDirectory }

db.*

• db.status -> payload: { password, dataDirectory? }
• db.initialize_schema -> payload: { dataDirectory? }
• db.hydrate_workspace -> payload: { password, dataDirectory? }

ai.* (bridge only, execution remains Python)

• ai.health -> no payload
• ai.summarize_entry -> payload: { content, fileStem? }
• ai.summarize_all -> payload: { entries }
• ai.chat -> payload: { prompt }
• ai.embed -> payload: { content }

speech.* (bridge/orchestration in C#, execution remains Python)

• speech.devices.list -> no payload
• speech.transcribe -> payload: { audioBase64|audio_base64 OR text, engine?, whisperModel|whisper_model?, simulateDelayMs|simulate_delay_ms? }

config.*

• config.get -> no payload

DTO Notes (C#)

The C# side uses DTOs as command/service contracts in journal-master/journal/Journal.Core/Dtos/, including:

• EntrySearchRequestDto, EntrySearchResultDto
• CreateFragmentDto, UpdateFragmentDto, FragmentDto
• SpeechTranscribeRequestDto, SpeechTranscribeResultDto, SpeechDeviceDto
• AiHealthDto

Primary action routing is implemented in:

• journal-master/journal/Journal.Core/Entry.cs