# Claudly -Claude Conversation Tracker API

Base URL: https://claudly.cloud

## Authentication

Two-step login process:
1. POST /login with your Username (email). A JWT is emailed to you.
   If the email does not exist, a new account is automatically created.
2. Use the JWT as the Token parameter on all authenticated endpoints.
3. JWTs are HMAC-SHA256 signed, valid for 1 hour, revocable via /logout.
4. Login is rate-limited to 5 requests per email per hour.

All endpoints require authentication (Username + JWT) except /login, /help, and /suggestions.

---

## Endpoints

### 1. GET /help
Returns this documentation.

### 2. POST /login
Sends a signed JWT to the user's email. Auto-registers if email is new.
Content-Type: application/json

Required: Username
Optional: DisplayName (used when auto-registering)

### 3. POST /logout
Revokes all active JWTs for the user.
Content-Type: application/json

Required: Username, Token (JWT)

### 4. POST /save
Saves or updates a conversation. Matches by SessionID or ConversationID.
Content-Type: application/json

Required: Username, Token, plus SessionID or ConversationID (at least one)
Optional: Title, Summary, ServerName, WorkingDirectory, Tags,
          IsCompleted (true/false)

### 5. GET /recall
Retrieves a conversation by SessionID or ConversationID.
/recall?Username=x&Token=x&SessionID=abc123
/recall?Username=x&Token=x&ConversationID=1

### 6. GET /list
Lists all conversations (most recent first).
/list?Username=x&Token=x[&Tag=portal5][&Search=keyword][&Top=50]

### 7. POST /delete
Soft-deletes a conversation.
Content-Type: application/json

Required: Username, Token, ConversationID (or SessionID)

### 8. GET /pending
Returns due reminders that have not been emailed yet.
/pending?Username=x&Token=x

### 9. GET /search
Searches conversations by keyword across Title, Summary, and Tags.
/search?Username=x&Token=x&q=keyword[&Top=50]

### 10. POST /add-history
Adds a history entry to a conversation.
Content-Type: application/json

Required: Username, Token, ConversationID, Action (short description of what was done)
Optional: Details (longer details), ServerName

### 11. GET /get-history
Gets all history entries for a conversation.
/get-history?Username=x&Token=x&ConversationID=1

### 12. POST /add-reminder
Creates a reminder for a conversation.
Content-Type: application/json

Required: Username, Token, ConversationID, Title, ReminderDate (ISO 8601, e.g. 2026-03-20 09:00)
Optional: Note

### 13. GET /get-reminders
Gets all reminders for a user (optionally filtered by ConversationID).
/get-reminders?Username=x&Token=x[&ConversationID=1]

### 14. GET /process-reminders (internal)
Sends reminder emails for all due reminders. Localhost only.
Max 3 attempts per reminder. Called by server on a schedule.
/process-reminders

### 15. POST /suggest
Submit a feature request or improvement suggestion.
Content-Type: application/json

Required: Username, Token, Title
Optional: Details, DisplayName (updates your profile), Anonymous (true/false, default true), ShowEmail (true/false, default false)

When Anonymous=true (default): listed as "Anonymous"
When Anonymous=false, ShowEmail=false: your DisplayName is shown
When Anonymous=false, ShowEmail=true: your email is shown

### 16. GET /suggestions
View all suggestions from all users, sorted by votes. No auth required.
/suggestions

### 17. POST /upvote
Upvote a suggestion. One vote per user per suggestion.
Content-Type: application/json

Required: Username, Token, SuggestionID

---

## Examples

### Login and get a JWT
curl -X POST https://claudly.cloud/login \
  -H 'Content-Type: application/json' \
  -d '{"Username":"you@example.com"}'
# JWT is emailed from support@claudly.cloud. Use it as Token on all other calls.

### Save a conversation
JWT="eyJhbG..."
curl -X POST https://claudly.cloud/save \
  -H 'Content-Type: application/json' \
  -d '{
    "Username":"you@example.com",
    "Token":"'$JWT'",
    "SessionID":"your-session-id",
    "Title":"My conversation",
    "Summary":"What this conversation was about",
    "ServerName":"'$(hostname)'",
    "WorkingDirectory":"'$(pwd)'",
    "Tags":"project,feature"
  }'

### List conversations
curl 'https://claudly.cloud/list?Username=you@example.com&Token=JWT'
# Filter by tag:
curl 'https://claudly.cloud/list?Username=you@example.com&Token=JWT&Tag=claudly'

### Add a history entry
curl -X POST https://claudly.cloud/add-history \
  -H 'Content-Type: application/json' \
  -d '{
    "Username":"you@example.com",
    "Token":"'$JWT'",
    "ConversationID":1,
    "Action":"Implemented feature X",
    "Details":"Added new endpoint, updated tests",
    "ServerName":"'$(hostname)'"
  }'

### Set a reminder
curl -X POST https://claudly.cloud/add-reminder \
  -H 'Content-Type: application/json' \
  -d '{
    "Username":"you@example.com",
    "Token":"'$JWT'",
    "ConversationID":1,
    "Title":"Follow up on deployment",
    "ReminderDate":"2026-03-20 09:00",
    "Note":"Check if the API is stable after the weekend"
  }'

---

## Notes
- JWTs expire after 1 hour. Call /login again to get a new one.
- /logout revokes all active JWTs immediately (stored in sessions table).
- Conversations are soft-deleted (/delete sets IsActive=0, data is preserved).
- /process-reminders is restricted to localhost and called by a scheduled task.
  Max 3 email attempts per reminder. Results are logged in the reminders table.
- The Token field in all requests is a JWT. There are no user passwords.