feat: v0.1.0 - geolocation capture, calendar, search, Starlight docs site
- Automatic browser geolocation capture on event creation - Reverse geocoding via Nominatim API for place names - Full-text search with SQLite FTS5 - Calendar view for browsing past entries - DateNavigator component for day navigation - SearchModal with Ctrl+K shortcut - QuickAddWidget with Ctrl+J shortcut - Starlight documentation site with GitHub Pages deployment - Multiple AI provider support (Groq, OpenAI, Anthropic, Ollama, LM Studio) - Multi-user registration support BREAKING: Events now include latitude/longitude/placeName fields
This commit is contained in:
lotherk
254
docs/api.md
Normal file
254
docs/api.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# API Reference
|
||||
|
||||
Base URL: `/api/v1`
|
||||
|
||||
Authentication: All requests require an API key in the `Authorization` header:
|
||||
```
|
||||
Authorization: Bearer <api_key>
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
### Register User
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/v1/auth/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email": "user@example.com", "password": "password123"}'
|
||||
```
|
||||
|
||||
### Login
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email": "user@example.com", "password": "password123"}'
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"token": "jwt_token",
|
||||
"userId": "user_id"
|
||||
},
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
### Create API Key
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/v1/auth/api-key \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer <token>" \
|
||||
-d '{"name": "my-app"}'
|
||||
```
|
||||
|
||||
## Events
|
||||
|
||||
### Create Event
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/v1/events \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer <api_key>" \
|
||||
-d '{
|
||||
"date": "2026-03-27",
|
||||
"type": "event",
|
||||
"content": "Had a great meeting about the new project"
|
||||
}'
|
||||
```
|
||||
|
||||
Valid types: `event`, `text`, `photo`, `voice`, `health`
|
||||
|
||||
### Get Event
|
||||
```bash
|
||||
curl http://localhost:3000/api/v1/events/<event_id> \
|
||||
-H "Authorization: Bearer <api_key>"
|
||||
```
|
||||
|
||||
### Update Event
|
||||
```bash
|
||||
curl -X PUT http://localhost:3000/api/v1/events/<event_id> \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer <api_key>" \
|
||||
-d '{"content": "Updated content"}'
|
||||
```
|
||||
|
||||
Note: Events cannot be updated if a diary page has been generated for that date.
|
||||
|
||||
### Delete Event
|
||||
```bash
|
||||
curl -X DELETE http://localhost:3000/api/v1/events/<event_id> \
|
||||
-H "Authorization: Bearer <api_key>"
|
||||
```
|
||||
|
||||
Note: Events cannot be deleted if a diary page has been generated for that date.
|
||||
|
||||
## Days
|
||||
|
||||
### List Days
|
||||
```bash
|
||||
curl http://localhost:3000/api/v1/days \
|
||||
-H "Authorization: Bearer <api_key>"
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"date": "2026-03-27",
|
||||
"eventCount": 5,
|
||||
"hasJournal": true
|
||||
}
|
||||
],
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
### Get Day Details
|
||||
```bash
|
||||
curl http://localhost:3000/api/v1/days/2026-03-27 \
|
||||
-H "Authorization: Bearer <api_key>"
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"date": "2026-03-27",
|
||||
"events": [...],
|
||||
"journal": {...}
|
||||
},
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
### Delete Day (and journal)
|
||||
```bash
|
||||
curl -X DELETE http://localhost:3000/api/v1/days/2026-03-27 \
|
||||
-H "Authorization: Bearer <api_key>"
|
||||
```
|
||||
|
||||
## Journal
|
||||
|
||||
### Generate Diary Page
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/v1/journal/generate/2026-03-27 \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer <api_key>" \
|
||||
-d '{"instructions": "Focus more on the technical aspects"}'
|
||||
```
|
||||
|
||||
The `instructions` field is optional. If provided, it will be appended to the prompt for regeneration.
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"journal": {
|
||||
"id": "...",
|
||||
"date": "2026-03-27",
|
||||
"content": "Generated diary content...",
|
||||
"eventCount": 5,
|
||||
"generatedAt": "2026-03-27T10:30:00Z"
|
||||
},
|
||||
"task": {
|
||||
"id": "...",
|
||||
"type": "journal_generate",
|
||||
"status": "completed",
|
||||
"provider": "groq",
|
||||
"model": "llama-3.3-70b-versatile"
|
||||
}
|
||||
},
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
### Get Journal
|
||||
```bash
|
||||
curl http://localhost:3000/api/v1/journal/2026-03-27 \
|
||||
-H "Authorization: Bearer <api_key>"
|
||||
```
|
||||
|
||||
### Delete Journal
|
||||
```bash
|
||||
curl -X DELETE http://localhost:3000/api/v1/journal/2026-03-27 \
|
||||
-H "Authorization: Bearer <api_key>"
|
||||
```
|
||||
|
||||
Deleting the journal unlocks events for editing.
|
||||
|
||||
### Get Journal Tasks
|
||||
```bash
|
||||
curl http://localhost:3000/api/v1/journal/2026-03-27/tasks \
|
||||
-H "Authorization: Bearer <api_key>"
|
||||
```
|
||||
|
||||
## Tasks
|
||||
|
||||
### Get Task
|
||||
```bash
|
||||
curl http://localhost:3000/api/v1/tasks/<task_id> \
|
||||
-H "Authorization: Bearer <api_key>"
|
||||
```
|
||||
|
||||
Response includes full request/response JSON for debugging.
|
||||
|
||||
## Settings
|
||||
|
||||
### Get Settings
|
||||
```bash
|
||||
curl http://localhost:3000/api/v1/settings \
|
||||
-H "Authorization: Bearer <api_key>"
|
||||
```
|
||||
|
||||
### Update Settings
|
||||
```bash
|
||||
curl -X PUT http://localhost:3000/api/v1/settings \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer <api_key>" \
|
||||
-d '{
|
||||
"aiProvider": "groq",
|
||||
"providerSettings": {
|
||||
"groq": {
|
||||
"apiKey": "your-api-key",
|
||||
"model": "llama-3.3-70b-versatile"
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## AI Providers
|
||||
|
||||
### Test Connection
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/v1/ai/test \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer <api_key>" \
|
||||
-d '{
|
||||
"provider": "groq",
|
||||
"apiKey": "your-api-key",
|
||||
"model": "llama-3.3-70b-versatile"
|
||||
}'
|
||||
```
|
||||
|
||||
Supported providers: `groq`, `openai`, `anthropic`, `ollama`, `lmstudio`
|
||||
|
||||
## Error Responses
|
||||
|
||||
All endpoints return errors in this format:
|
||||
```json
|
||||
{
|
||||
"data": null,
|
||||
"error": {
|
||||
"code": "ERROR_CODE",
|
||||
"message": "Human readable message"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Common error codes:
|
||||
- `UNAUTHORIZED` - Invalid or missing API key
|
||||
- `NOT_FOUND` - Resource not found
|
||||
- `NO_EVENTS` - No events for diary generation
|
||||
- `NO_AI_CONFIG` - AI provider not configured
|
||||
- `EVENT_IMMUTABLE` - Cannot modify event (diary exists)
|
||||
Reference in New Issue
Block a user