Story Endpoints

Overview

Story endpoints handle the core journaling functionality: creating, reading, and managing personal narratives.

All story endpoints require authentication. Users can only access and modify their own stories.

Save Journal Entry

Create a new journal entry with automatic AI analysis.

Request Body

content

string

required

Journal entry content (must be non-empty)

title

string

Entry title (default: "Journal Entry {date}")

mood

string

User’s mood (default: "neutral")

Response

success

boolean

Always true on successful save

data

object

The created story object

Show story fields

string

Story UUID

author_id

string

User ID

author_wallet

string

User’s Ethereum address

title

string

Entry title

content

string

Entry content

mood

string

User’s mood

Example Request

curl -X POST https://istory.vercel.app/api/journal/save \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "A Day of Reflection",
    "content": "Today I realized that taking breaks is just as important as working hard. I spent the afternoon walking in the park and it gave me so much clarity.",
    "mood": "peaceful",
    "tags": ["self-care", "mindfulness"]
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "author_id": "456e7890-e89b-12d3-a456-426614174111",
    "author_wallet": "0x742d35cc6634c0532925a3b844bc9e7595f0beb",
    "title": "A Day of Reflection",
    "content": "Today I realized that taking breaks is just as important as working hard...",
    "mood": "peaceful",
    "tags": ["self-care", "mindfulness"],
    "has_audio": false,
    "audio_url": null,
    "likes": 0,
    "comments_count": 0,
    "shares": 0,
    "created_at": "2026-03-04T10:30:00.000Z"
  },
  "message": "Journal entry saved successfully!"
}

Background Processing

Saving a journal entry automatically triggers two background operations:

AI Analysis - Calls /api/ai/analyze to extract metadata
CRE Verification - Calls /api/cre/trigger for blockchain attestation

These operations are non-blocking (fire-and-forget). The story is saved immediately even if background tasks fail.

Error Responses

Show 400 Bad Request

{ "error": "Content is required" }

Show 404 Not Found

{ "error": "User not found" }

Authenticated user does not exist in the database.

Get User Stories

Fetch all stories for the authenticated user.

Response

stories

object[]

Array of story objects (ordered by story_date descending)

Example Request

curl https://istory.vercel.app/api/stories \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "stories": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "author_id": "456e7890-e89b-12d3-a456-426614174111",
      "title": "A Day of Reflection",
      "content": "Today I realized...",
      "mood": "peaceful",
      "tags": ["self-care"],
      "created_at": "2026-03-04T10:30:00.000Z",
      "story_date": "2026-03-04T00:00:00.000Z",
      "is_public": false,
      "likes": 0
    },
    // ... more stories
  ]
}

Create Story (Advanced)

Create a story with full control over all fields (used for sync operations).

Request Body

author_id

string

required

User ID (must match authenticated user)

author_wallet

string

required

Ethereum address (must match user’s wallet)

title

string

required

Story title

content

string

required

Story content

has_audio

boolean

Whether audio exists (default: false)

audio_url

string

Audio file URL

Response

story

object

The created story object

Example Request

curl -X POST https://istory.vercel.app/api/stories \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "author_id": "456e7890-e89b-12d3-a456-426614174111",
    "author_wallet": "0x742d35cc6634c0532925a3b844bc9e7595f0beb",
    "title": "Weekend Adventure",
    "content": "Went hiking in the mountains...",
    "mood": "excited",
    "tags": ["adventure", "nature"],
    "is_public": true,
    "story_date": "2026-03-02T00:00:00.000Z"
  }'

Error Responses

Show 400 Bad Request

{ "error": "Missing required fields (author_id, author_wallet, title, content)." }

Show 401 Unauthorized

{ "error": "User not found" }

Show 401 Unauthorized - Wallet Mismatch

{ "error": "Wallet mismatch" }

The provided author_wallet doesn’t match the user’s actual wallet address.

Show 403 Forbidden

{ "error": "Forbidden" }

The author_id doesn’t match the authenticated user.

Story Metadata

After a story is created, AI analysis generates metadata stored in the story_metadata table:

interface StoryMetadata {
  story_id: string;
  themes: string[];
  emotional_tone: string;
  life_domain: string;
  intensity_score: number;        // 0.0-1.0
  significance_score: number;     // 0.0-1.0
  people_mentioned: string[];
  places_mentioned: string[];
  time_references: string[];
  brief_insight: string;
  is_canonical: boolean;          // "Important" flag
  created_at: string;
  updated_at: string;
}

Metadata is accessible via:

GET /api/stories - Includes metadata in response
Direct Supabase queries with joins

Best Practices

Use /journal/save

For new entries, use /api/journal/save for automatic background processing

Use /stories POST

For sync operations or when you need control over timestamps

Check Ownership

The API automatically verifies ownership - you cannot access other users’ stories

Handle Async Analysis

AI analysis is non-blocking - metadata may not be available immediately

Create Book Collection

Compile multiple stories into a book for NFT minting.

Request Body

author_id

string

required

User ID (must match authenticated user)

author_wallet

string

required

Ethereum address (must match user’s wallet)

title

string

required

Book title

story_ids

string[]

required

Array of story UUIDs to include (must be non-empty)

description

string

Book description

ipfs_hash

string

IPFS hash for NFT metadata

Response

success

boolean

Always true on successful creation

book

object

The created book object

Show book fields

string

Book UUID

author_id

string

User ID

author_wallet

string

Ethereum address

title

string

Book title

description

string | null

Book description

story_ids

string[]

Array of story UUIDs

ipfs_hash

string | null

IPFS metadata hash

created_at

string

ISO 8601 timestamp

Example Request

cURL

curl -X POST https://istory.vercel.app/api/books \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "author_id": "user-uuid",
    "author_wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "title": "My Journey 2026",
    "story_ids": ["story-uuid-1", "story-uuid-2"],
    "description": "A collection of my most memorable moments"
  }'

Smart Contracts

API Reference

Architecture

Story Endpoints

Overview

Save Journal Entry

Request Body

Response

Example Request

Example Response

Background Processing

Error Responses

Get User Stories

Response

Example Request

Example Response

Create Story (Advanced)

Request Body

Response

Example Request

Error Responses

Story Metadata

Best Practices

Use /journal/save

Use /stories POST

Check Ownership

Handle Async Analysis

Create Book Collection

Request Body

Response

Example Request

Next Steps

AI Analysis

Social Features

Build docs developers (and LLMs) love

Smart Contracts

API Reference

Architecture

​Overview

​Save Journal Entry

​Request Body

​Response

​Example Request

​Example Response

​Background Processing

​Error Responses

​Get User Stories

​Response

​Example Request

​Example Response

​Create Story (Advanced)

​Request Body

​Response

​Example Request

​Error Responses

​Story Metadata

​Best Practices

Use /journal/save

Use /stories POST

Check Ownership

Handle Async Analysis

​Create Book Collection

​Request Body

​Response

​Example Request

​Next Steps

AI Analysis

Social Features

Build docs developers (and LLMs) love

Overview

Save Journal Entry

Request Body

Response

Example Request

Example Response

Background Processing

Error Responses

Get User Stories

Response

Example Request

Example Response

Create Story (Advanced)

Request Body

Response

Example Request

Error Responses

Story Metadata

Best Practices

Create Book Collection

Request Body

Response

Example Request

Next Steps