Entries API

Get All Entries

curl http://127.0.0.1:5000/api/entries

{
  "entries": {
    "2024-03-15": {
      "text": "Today was incredibly productive. Finished the project.",
      "photos": [],
      "tags": ["work", "productivity"],
      "sentiment": {
        "compound": 0.742,
        "mood": "positive",
        "scores": {
          "positive": 0.352,
          "negative": 0.021,
          "neutral": 0.627
        }
      },
      "themes": ["work", "productivity"],
      "word_count": 8,
      "updatedAt": "2024-03-15T14:30:22.123Z"
    },
    "2024-03-14": {
      "text": "Feeling stressed about deadlines.",
      "photos": [],
      "tags": ["stress"],
      "sentiment": {
        "compound": -0.431,
        "mood": "negative",
        "scores": {
          "positive": 0.0,
          "negative": 0.342,
          "neutral": 0.658
        }
      },
      "themes": ["work", "emotions"],
      "word_count": 5,
      "updatedAt": "2024-03-14T19:45:10.456Z"
    }
  },
  "metadata": {
    "created_at": "2024-01-01T00:00:00.000Z"
  }
}

Response

entries

object

required

Dictionary of all journal entries, keyed by date (YYYY-MM-DD)

metadata

object

Journal metadata including creation timestamp

Get Single Entry

curl http://127.0.0.1:5000/api/entries/2024-03-15

{
  "text": "Today was incredibly productive. Finished the project.",
  "photos": [],
  "tags": ["work", "productivity"],
  "sentiment": {
    "compound": 0.742,
    "mood": "positive",
    "scores": {
      "positive": 0.352,
      "negative": 0.021,
      "neutral": 0.627
    }
  },
  "themes": ["work", "productivity"],
  "word_count": 8,
  "updatedAt": "2024-03-15T14:30:22.123Z"
}

Parameters

date_key

string

required

Date in YYYY-MM-DD format (e.g., 2024-03-15)

Response

Returns a single entry object or 404 if not found.

text

string

required

The journal entry content (up to 50,000 characters)

photos

array

Array of photo URLs or paths (max 10)

Create/Update Entry

curl -X POST http://127.0.0.1:5000/api/entries/2024-03-15 \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Today was great! I finished my project and went for a run.",
    "tags": ["work", "exercise"],
    "photos": []
  }'

{
  "saved": true,
  "entry": {
    "text": "Today was great! I finished my project and went for a run.",
    "photos": [],
    "tags": ["work", "exercise"],
    "sentiment": {
      "compound": 0.832,
      "mood": "very_positive",
      "scores": {
        "positive": 0.425,
        "negative": 0.0,
        "neutral": 0.575
      }
    },
    "themes": ["work", "health"],
    "word_count": 12,
    "updatedAt": "2024-03-15T20:15:30.789Z"
  },
  "encouragement": "What a wonderful day! Your positivity shines through your words."
}

Parameters

date_key

string

required

Date in YYYY-MM-DD format

Request Body

text

string

required

Journal entry text (max 50,000 characters)

Response

saved

boolean

Indicates successful save

entry

object

Complete entry object with automatically generated fields

encouragement

string

Empathetic message based on detected mood

Automatic Processing

When you save an entry, the API automatically:

Analyzes sentiment using NLTK VADER (local)
Detects themes using keyword matching
Counts words
Adds timestamp
Generates empathetic response based on mood

Empty Entry Deletion

If you save an entry with no text and no photos, it will be automatically deleted:

{
  "deleted": true
}

Delete Entry

curl -X DELETE http://127.0.0.1:5000/api/entries/2024-03-15

{
  "deleted": true
}

Parameters

date_key

string

required

Date in YYYY-MM-DD format

Response

deleted

boolean

true if entry was deleted, error if not found

Error Responses

Invalid Date Format

{
  "error": "Invalid date format. Use YYYY-MM-DD"
}

HTTP Status: 400

Entry Not Found

{
  "error": "Entry not found"
}

HTTP Status: 404

Text Too Long

{
  "error": "Text exceeds maximum length of 50000 characters"
}

HTTP Status: 400

Too Many Photos

{
  "error": "Maximum 10 photos allowed"
}

HTTP Status: 400

Data Validation

The API validates:

Date format: Must be YYYY-MM-DD
Text length: Max 50,000 characters
Photos: Max 10 per entry
Tags: Max 10 tags, 30 characters each

Mood Labels

Sentiment analysis produces these mood labels:

Compound Score	Mood Label	Emoji
≥ 0.5	`very_positive`	😄
0.2 to 0.5	`positive`	🙂
-0.2 to 0.2	`neutral`	😐
-0.5 to -0.2	`negative`	😔
< -0.5	`very_negative`	😢

Theme Detection

The API automatically detects themes from your text:

work: job, office, meeting, project
family: mom, dad, parent, sibling
friends: hangout, party, social
health: gym, workout, exercise
food: breakfast, lunch, dinner
learning: study, read, course
emotions: happy, sad, anxious
travel: trip, vacation, flight
creativity: write, art, music

Empathetic Responses

Based on your entry’s mood, you’ll receive an empathetic response:

Mood	Example Response
Very Positive	”What a wonderful day! Your positivity shines through your words.”
Positive	”It sounds like things are going well. Keep nurturing those good moments.”
Neutral	”Thank you for reflecting today. Every entry helps you understand yourself better.”
Negative	”It seems like today had some challenges. Remember, it’s okay to have difficult days.”
Very Negative	”I hear that today was tough. Writing about it is a brave step. Be gentle with yourself.”

These endpoints power the year and month view navigation in the calendar UI.

Get Years with Entries

GET /api/years

Returns a list of years that have at least one journal entry.

curl http://127.0.0.1:5000/api/years

Response:

[2026, 2025, 2024]

Returns an array of years in descending order (newest first).

Get Months with Entries

GET /api/years/:year/months

Returns months (1-12) that have entries for the specified year.

curl http://127.0.0.1:5000/api/years/2026/months

Response:

[1, 2, 3]

Returns an array of month numbers in ascending order.

Get Days with Entries

GET /api/years/:year/months/:month/days

Returns detailed information about all days with entries in the specified month.

curl http://127.0.0.1:5000/api/years/2026/months/3/days

Response:

[
  {
    "day": 5,
    "key": "2026-03-05",
    "preview": "Today was a good day. I felt productive and...",
    "hasPhotos": false,
    "mood": "positive",
    "moodEmoji": "🙂"
  },
  {
    "day": 12,
    "key": "2026-03-12",
    "preview": "Struggled a bit today with work deadlines...",
    "hasPhotos": true,
    "mood": "neutral",
    "moodEmoji": "😐"
  }
]

day

integer

Day of the month (1-31)

key

string

Full date key in YYYY-MM-DD format

preview

string

First 50 characters of the entry text

hasPhotos

boolean

Whether the entry has attached photos

mood

string

Detected mood: very_positive, positive, neutral, negative, or very_negative

moodEmoji

string

Emoji representing the mood (😄, 🙂, 😐, 😔, 😢)

Next Steps

Stats API

Track streaks and mood distribution

Insights API

Discover patterns in your journaling

Overview

Endpoints

Get All Entries

Response

Get Single Entry

Parameters

Response

Create/Update Entry

Parameters

Request Body

Response

Automatic Processing

Empty Entry Deletion

Delete Entry

Parameters

Response

Error Responses

Invalid Date Format

Entry Not Found

Text Too Long

Too Many Photos

Data Validation

Mood Labels

Theme Detection

Empathetic Responses

Navigation Endpoints

Get Years with Entries

Get Months with Entries

Get Days with Entries

Next Steps

Stats API

Insights API

Build docs developers (and LLMs) love

Overview

Endpoints

​Get All Entries

​Response

​Get Single Entry

​Parameters

​Response

​Create/Update Entry

​Parameters

​Request Body

​Response

​Automatic Processing

​Empty Entry Deletion

​Delete Entry

​Parameters

​Response

​Error Responses

​Invalid Date Format

​Entry Not Found

​Text Too Long

​Too Many Photos

​Data Validation

​Mood Labels

​Theme Detection

​Empathetic Responses

​Navigation Endpoints

​Get Years with Entries

​Get Months with Entries

​Get Days with Entries

​Next Steps

Stats API

Insights API

Build docs developers (and LLMs) love

Get All Entries

Response

Get Single Entry

Parameters

Response

Create/Update Entry

Parameters

Request Body

Response

Automatic Processing

Empty Entry Deletion

Delete Entry

Parameters

Response

Error Responses

Invalid Date Format

Entry Not Found

Text Too Long

Too Many Photos

Data Validation

Mood Labels

Theme Detection

Empathetic Responses

Navigation Endpoints

Get Years with Entries

Get Months with Entries

Get Days with Entries

Next Steps