Skip to main content

​
Introduction

The iStory API provides a comprehensive REST interface for building Web3-powered voice journaling applications. All endpoints require authentication and are protected by rate limiting.

​
Base URL

https://istory.vercel.app/api
For local development: 
http://localhost:3000/api

​
Authentication

All API endpoints require a Bearer token in the Authorization header. iStory supports two authentication methods:
  1. Wallet Authentication (custom JWT)
  2. Google OAuth (Supabase session JWT)
See Authentication for detailed implementation.

​
Rate Limits

API routes are protected by a rate limiting middleware with route-specific limits:
Route PatternLimitWindow
/api/ai/*10 requests1 minute
/api/auth/*20 requests1 minute
/api/email/send5 requests1 minute
/api/cre/callback30 requests1 minute
/api/waitlist10 requests1 minute
All other /api/*60 requests1 minute
Rate limit information is returned in response headers: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
When rate limited, the API returns: 
{
  "error": "Too many requests. Please try again later."
}
Status: 429 Too Many Requests
Headers: Retry-After: 60

​
CORS

The API supports cross-origin requests from these origins:
  • http://localhost:8081 (Expo dev)
  • http://localhost:19006 (Expo web)
  • http://localhost:3000 (Next.js dev)
  • https://e-story-dapp.vercel.app
  • https://istory.vercel.app
Allowed methods: GET, POST, PUT, DELETE, PATCH, OPTIONS
Allowed headers: Content-Type, Authorization

​
Response Format

​
Success Response

{
  "success": true,
  "data": { /* response data */ }
}

​
Error Response

{
  "error": "Human-readable error message"
}
Error messages never leak internal implementation details or stack traces.

​
Status Codes

CodeMeaning
200Success
400Bad Request - Invalid input
401Unauthorized - Missing or invalid token
403Forbidden - Insufficient permissions
404Not Found
409Conflict - Duplicate resource or concurrent operation
422Unprocessable Entity - Valid format but semantic error
429Too Many Requests - Rate limit exceeded
500Internal Server Error
502Bad Gateway - External service error

​
API Sections

Authentication

Wallet signature and OAuth login flows

AI Endpoints

Transcription, enhancement, analysis, and reflections

Story Endpoints

Create, read, and manage journal entries

Social Endpoints

Likes, follows, and social interactions

​
Security

The API implements a layered security model: Layer 0: Security headers (CSP, X-Frame-Options, CORS)
Layer 1: Rate limiting (route-specific)
Layer 2: Bearer token authentication
Layer 3: Input validation (size limits, MIME types, text length)
Layer 4: Ownership verification (users can only modify their own resources)
Never expose your SUPABASE_SERVICE_ROLE_KEY or JWT_SECRET in client-side code.

​
SDK Support

​
JavaScript/TypeScript

const response = await fetch('https://istory.vercel.app/api/stories', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

​
cURL

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

​
Next Steps

Authentication Guide

Learn how to authenticate with wallet signatures

AI Integration

Integrate voice transcription and AI analysis

Build docs developers (and LLMs) love

Get started for freeTalk to us