API Documentation

Access structured data from Marcus Aurelius' Meditations. All endpoints return JSON data.

Principles API

Access Stoic principles extracted from the Meditations.

Get Today's Principle

GET /api/principle

Returns the principle for today (based on day of year).

Get Random Principle

GET /api/principle/random

Returns a random principle from the collection.

Get Specific Principle

GET /api/principle/{id}

Returns a specific principle by ID (1-based indexing).

Books API

Access individual books and meditations from the Meditations.

Get Random Book

GET /api/book/random

Returns a random book with all its meditations.

Get Book

GET /api/book/{book_number}

Returns a specific book with all its meditations (e.g., /api/book/4).

Get Specific Meditation

GET /api/book/{book_number}.{meditation_number}

Returns a specific meditation (e.g., /api/book/4.1).

Response Format

Principle Response

{
  "Principles": "Focus on what you can control.",
  "Context": "Changing how you see things often matters more than changing the things themselves.",
  "Tags": ["control", "perspective", "dichotomy of control"],
  "ref": ["4.3", "4.4", "8.47"]
}

Book Response

{
  "book_info": {
    "book_number": 4,
    "title": "On the Mind and Inner Retreat",
    "themes": ["mind", "inner retreat", "tranquility"],
    "meditation_count": 50
  },
  "meditations": [
    {
      "id": "4.1",
      "book": 4,
      "title": "Meditation Title",
      "content": "Meditation content...",
      "tags": ["virtue", "wisdom"]
    }
  ]
}

Single Meditation Response

{
  "id": "4.1",
  "book": 4,
  "title": "Meditation Title",
  "content": "Meditation content...",
  "location": "Rome",
  "teacher": "Teacher Name",
  "tags": ["virtue", "wisdom"]
}

Error Responses

All endpoints return appropriate HTTP status codes and error messages for invalid requests.

{
  "error": "Invalid principle ID"
}

Examples

Get Today's Principle

curl https://meditations.one/api/principle

Get Book 4, Meditation 1

curl https://meditations.one/api/book/4.1

Get Random Book

curl https://meditations.one/api/book/random