AI Endpoints

Overview

iStory’s AI endpoints power the core journaling experience:

Transcription - Convert voice recordings to text (ElevenLabs Scribe)
Enhancement - Improve grammar and flow (Gemini 2.5 Flash)
Analysis - Extract themes and insights (Gemini 2.5 Flash)
Reflection - Generate weekly summaries (Gemini 2.5 Flash)

All AI endpoints require authentication and are rate limited to 10 requests per minute.

Transcribe Audio

Convert audio files to text using ElevenLabs Scribe model.

Request

Content-Type: multipart/form-data

file

File

required

Audio file (max 25MB)Supported formats:

audio/webm, audio/wav, audio/mp3, audio/mpeg
audio/ogg, audio/flac, audio/m4a, audio/mp4
audio/x-m4a, audio/aac, video/webm

Response

text

string

Transcribed text from the audio file

Example Request

curl -X POST https://istory.vercel.app/api/ai/transcribe \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]"

Example Response

{
  "text": "Today was an incredible day. I finally finished the project I've been working on for months, and the client loved it. Feeling grateful and accomplished."
}

Error Responses

Show 400 Bad Request - No File

{ "error": "No audio file provided" }

Show 400 Bad Request - File Too Large

{ "error": "File too large. Maximum size is 25MB." }

Show 400 Bad Request - Invalid Type

{ "error": "Invalid file type. Only audio files are accepted." }

Show 422 Unprocessable Entity

{ "error": "Transcription returned empty result. Please try again." }

This can occur with very short recordings or pure silence.

Show 502 Bad Gateway

{ "error": "Transcription service authentication failed. Please check server configuration." }

Indicates an issue with the ElevenLabs API key.

Implementation Details

// Features enabled:
modelId: "scribe_v1"
tagAudioEvents: true      // Detects laughter, pauses, etc.
languageCode: "eng"       // English
diarize: false            // Single speaker

Enhance Text

Improve grammar, spelling, and flow while preserving the original meaning.

Request Body

text

string

required

Raw text to enhance (max 50,000 characters)

Response

text

string

Enhanced text with improved grammar and vocabulary

Example Request

curl -X POST https://istory.vercel.app/api/ai/enhance \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "today i went to the store and bought some stuff it was good"}'

Example Response

{
  "text": "Today, I went to the store and bought some supplies. It was a pleasant experience."
}

Error Responses

Show 400 Bad Request - No Text

{ "error": "No text provided" }

Show 400 Bad Request - Text Too Long

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

Enhancement Guidelines

The AI is instructed to:

Fix grammar and spelling errors
Improve flow and vocabulary
Keep the original personal tone
Not change the underlying meaning
Not add fictional events

The enhanced text may be shorter or longer than the original, but the meaning remains intact.

Analyze Story

Extract structured metadata and insights from a journal entry.

Request Body

storyId

string

required

UUID of the story to analyze

storyText

string

required

Full story content (min 50, max 10,000 characters)

Response

success

boolean

Always true on successful analysis

metadata

object

Structured metadata saved to database

Show metadata fields

themes

string[]

1-5 key themes (e.g., ["growth", "family", "resilience"])

emotional_tone

string

One of: reflective, joyful, anxious, hopeful, melancholic, grateful, frustrated, peaceful, excited, uncertain, neutral

life_domain

string

One of: work, relationships, health, identity, growth, creativity, spirituality, family, adventure, learning, general

intensity_score

number

Emotional intensity (0.0-1.0)

significance_score

number

Life story importance (0.0-1.0)

people_mentioned

string[]

Names of people mentioned

places_mentioned

string[]

Specific locations mentioned

time_references

string[]

Time phrases (e.g., ["last summer", "when I was 12"])

insight

string

One-sentence compassionate observation about the story’s meaning

Example Request

curl -X POST https://istory.vercel.app/api/ai/analyze \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "storyId": "123e4567-e89b-12d3-a456-426614174000",
    "storyText": "Today I had an important conversation with my mom about my career. She finally understood why I left my corporate job to pursue my passion for art. It felt liberating."
  }'

Example Response

{
  "success": true,
  "metadata": {
    "themes": ["family", "identity", "freedom", "career"],
    "emotional_tone": "hopeful",
    "life_domain": "relationships",
    "intensity_score": 0.75,
    "significance_score": 0.85,
    "people_mentioned": ["mom"],
    "places_mentioned": [],
    "time_references": ["today"],
    "brief_insight": "This represents a significant breakthrough in family communication and personal authenticity."
  },
  "insight": "This represents a significant breakthrough in family communication and personal authenticity."
}

Error Responses

Show 400 Bad Request - Missing Fields

{ "error": "Missing required fields: storyId and storyText" }

Show 400 Bad Request - Content Too Short

{ "error": "Story text must be at least 50 characters" }

Show 403 Forbidden

{ "error": "Forbidden" }

You can only analyze your own stories.

Show 409 Conflict

{ "error": "Analysis already in progress for this story" }

Prevents concurrent analysis requests for the same story.

Show 429 Too Many Requests

{ "error": "Rate limit exceeded. Please try again later." }

Headers: Retry-After: 60
Limit: 30 requests per minute per story.

Performance

Retry logic: 3 attempts with exponential backoff (1s, 2s, 4s)
Truncation: Content >10,000 characters is truncated at word boundary
Timeout handling: Automatic retry on Gemini API timeouts

Analysis is typically triggered automatically when saving a story via /api/journal/save.

Generate Weekly Reflection

Generate a compassionate summary of the user’s journal entries from the past week.

Request Body

userId

string

required

User ID (UUID)

userWallet

string

required

User’s Ethereum address

Response

success

boolean

Always true on successful generation

reflection

object

Weekly reflection object

Show reflection fields

reflection_text

string

2-3 paragraph compassionate reflection

themes_identified

string[]

Key themes across all entries

dominant_tone

string

Most common emotional tone

dominant_domain

string

Most common life domain

stories_analyzed

string[]

Array of story IDs included in reflection

canonical_weight

number

Canonical stories are weighted 2x (sum of weights)

week_start

string

ISO 8601 timestamp (Sunday 00:00:00)

week_end

string

ISO 8601 timestamp (Saturday 23:59:59)

storiesAnalyzed

number

Number of stories included in reflection

canonicalWeight

number

Weight score (canonical stories count 2x)

Example Request

curl -X POST https://istory.vercel.app/api/ai/reflection \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "userWallet": "0x742d35cc6634c0532925a3b844bc9e7595f0beb"
  }'

Example Response

{
  "success": true,
  "reflection": {
    "id": "456e7890-e89b-12d3-a456-426614174111",
    "reflection_text": "This week, your entries reveal a strong focus on personal growth and creative expression. You've been navigating changes in your career while maintaining meaningful connections with family.\n\nThere's a notable sense of hope and determination running through your stories, particularly around your decision to pursue art professionally. The conversation with your mom stands out as a key moment of mutual understanding and validation.\n\nYour reflections show increasing clarity about your values and priorities. Continue to honor these insights as you move forward.",
    "themes_identified": ["growth", "family", "creativity", "identity", "career"],
    "dominant_tone": "hopeful",
    "dominant_domain": "growth",
    "stories_analyzed": ["123e4567-e89b-12d3-a456-426614174000", "...3 more"],
    "canonical_weight": 6.0,
    "week_start": "2026-03-02T00:00:00.000Z",
    "week_end": "2026-03-08T23:59:59.999Z",
    "created_at": "2026-03-04T10:30:00.000Z"
  },
  "storiesAnalyzed": 4,
  "canonicalWeight": 6.0
}

Error Responses

Show 400 Bad Request

{ "error": "Missing required fields: userId and userWallet" }

Show 429 Too Many Requests

{
  "error": "You can only generate one reflection per week",
  "nextAvailable": "2026-03-09T00:00:00.000Z",
  "existingReflection": { /* existing reflection object */ }
}

Reflections are limited to 1 per week (7-day cooldown).

Fetch Existing Reflections

Query Parameters:

userId (required) - User ID
limit (optional) - Number of reflections to fetch (default: 5)

Response:

{
  "reflections": [ /* array of reflection objects */ ],
  "canGenerate": false,
  "currentWeekStart": "2026-03-02T00:00:00.000Z"
}

Special Cases

Show Empty Week

If the user has no stories from the past 7 days, the AI generates an encouraging message:

{
  "reflection_text": "It looks like you haven't captured any stories this week. Journaling is a powerful tool for self-reflection and growth. Consider setting aside a few minutes today to record your thoughts, experiences, or even small moments of gratitude.",
  "themes_identified": [],
  "dominant_tone": "hopeful",
  "dominant_domain": "growth"
}

Show Canonical Story Weighting

Stories marked as “Important” (canonical) are weighted 2x in the reflection:

// Stories with is_canonical: true are repeated in the prompt
if (isCanonical) {
  storyEntry = `**KEY MOMENT**\n${storyEntry}`;
  canonicalWeight += 2.0;
}

Reflection Guidelines

The AI is instructed to:

Write in a warm, encouraging tone (not clinical)
Focus on patterns, not individual events
Offer perspective without being prescriptive
Acknowledge sparse entries gently
Maximum 500 words

Rate Limits Summary

Endpoint	Limit	Window
`/api/ai/*`	10 requests	1 minute
`/api/ai/analyze` (per story)	30 requests	1 minute

Exceeding rate limits returns 429 Too Many Requests with a Retry-After: 60 header.

Smart Contracts

API Reference

Architecture

Overview

Transcribe Audio

Request

Response

Example Request

Example Response

Error Responses

Implementation Details

Enhance Text

Request Body

Response

Example Request

Example Response

Error Responses

Enhancement Guidelines

Analyze Story

Request Body

Response

Example Request

Example Response

Error Responses

Performance

Generate Weekly Reflection

Request Body

Response

Example Request

Example Response

Error Responses

Fetch Existing Reflections

Special Cases

Reflection Guidelines

Rate Limits Summary

Next Steps

Story Endpoints

Social Endpoints

Build docs developers (and LLMs) love

Smart Contracts

API Reference

Architecture

​Overview

​Transcribe Audio

​Request

​Response

​Example Request

​Example Response

​Error Responses

​Implementation Details

​Enhance Text

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

​Enhancement Guidelines

​Analyze Story

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

​Performance

​Generate Weekly Reflection

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

​Fetch Existing Reflections

​Special Cases

​Reflection Guidelines

​Rate Limits Summary

​Next Steps

Story Endpoints

Social Endpoints

Build docs developers (and LLMs) love

Overview

Transcribe Audio

Request

Response

Example Request

Example Response

Error Responses

Implementation Details

Enhance Text

Request Body

Response

Example Request

Example Response

Error Responses

Enhancement Guidelines

Analyze Story

Request Body

Response

Example Request

Example Response

Error Responses

Performance

Generate Weekly Reflection

Request Body

Response

Example Request

Example Response

Error Responses

Fetch Existing Reflections

Special Cases

Reflection Guidelines

Rate Limits Summary

Next Steps