Skip to main content

​
API Overview

Scribe Backend provides a RESTful API for generating personalized academic outreach emails using a multi-step AI pipeline. The API is built with FastAPI and follows OpenAPI 3.0 specifications.

​
Base URL

https://scribeapi.manitmishra.com

​
API Characteristics

Authentication

JWT-based authentication via Supabase Auth with Bearer token in Authorization header

Response Format

All responses are JSON with consistent error structure and HTTP status codes

Rate Limiting

Currently no hard rate limits, but batch operations limited to 100 items

Versioning

API version 1.0.0, future versions will use path-based versioning

​
Interactive Documentation

Scribe Backend provides auto-generated interactive API documentation powered by FastAPI’s Swagger UI: 
# Production
https://scribeapi.manitmishra.com/docs

# Local Development
http://localhost:8000/docs
The /docs endpoint allows you to:
  • Explore all available endpoints
  • View request/response schemas
  • Test API calls directly in the browser
  • Authenticate with JWT tokens
  • View example requests and responses
The interactive docs require authentication for protected endpoints. Click the Authorize button and enter your JWT token.

​
Response Format

All API responses follow a consistent JSON structure:

​
Success Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "660e8400-e29b-41d4-a716-446655440001",
  "recipient_name": "Dr. Jane Smith",
  "email_message": "...",
  "created_at": "2025-01-13T10:30:00Z"
}

​
Error Response

{
  "detail": "Email not found or you don't have permission to access it"
}
For validation errors: 
{
  "detail": [
    {
      "loc": ["body", "email_template"],
      "msg": "ensure this value has at least 10 characters",
      "type": "value_error.any_str.min_length"
    }
  ]
}

​
HTTP Status Codes

Scribe Backend uses standard HTTP status codes:
Status CodeMeaning
200 OKRequest succeeded
201 CreatedResource created successfully
202 AcceptedAsync task accepted for processing
400 Bad RequestInvalid request parameters
401 UnauthorizedMissing or invalid authentication
403 ForbiddenAuthenticated but insufficient permissions
404 Not FoundResource not found
422 Unprocessable EntityValidation error
429 Too Many RequestsRate limit exceeded
500 Internal Server ErrorServer error
503 Service UnavailableService temporarily unavailable

​
Pagination

List endpoints support pagination via query parameters:
​
limit
integer
default:"50"
Maximum number of items to return (max: 100)
​
offset
integer
default:"0"
Number of items to skip
Example: 
curl -X GET "https://scribeapi.manitmishra.com/api/email/?limit=20&offset=40" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Health Check

The API provides a public health check endpoint: 
curl -X GET https://scribeapi.manitmishra.com/health
Response: 
{
  "status": "healthy",
  "service": "scribe-api",
  "version": "1.0.0",
  "database": "connected",
  "environment": "production"
}
The health check endpoint is public and does not require authentication.

​
API Endpoints Summary

​
User Management

  • POST /api/user/init - Initialize user profile
  • GET /api/user/profile - Get current user profile

​
Email Generation

  • POST /api/email/generate - Generate single email (async)
  • GET /api/email/status/{task_id} - Check generation status
  • GET /api/email/{email_id} - Retrieve email by ID
  • GET /api/email/ - List user’s emails (paginated)
  • PATCH /api/email/{email_id} - Update email properties

​
Queue Management

  • POST /api/queue/batch - Submit batch (1-100 recipients)
  • GET /api/queue/ - Get all user’s queue items
  • DELETE /api/queue/{id} - Cancel pending queue item

​
Template Management

  • POST /api/templates/ - Generate template from resume

Authentication Guide

Learn how to authenticate API requests

Error Handling

Understand error responses and troubleshooting

User Endpoints

User management endpoint documentation

Email Endpoints

Email generation endpoint documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us