Developer Guide

API Endpoints

Available API routes

API Endpoints

Complete reference for all API endpoints in Prompt Stack. RESTful APIs built with FastAPI, fully documented and type-safe.

📡 API Base URL

http://localhost:8000/api

All endpoints are prefixed with /api and return standardized JSON responses.

API Documentation

Interactive Docs

Swagger UI for testing endpoints

http://localhost:8000/docs

OpenAPI Schema

Machine-readable API specification

http://localhost:8000/openapi.json

Response Format

All API endpoints return a standardized response format:

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
  message?: string;
  code?: string;
  meta?: {
    page?: number;
    limit?: number;
    total?: number;
  };
}

Success Response

{
  "success": true,
  "data": {
    "id": "123",
    "name": "Example Item",
    "created_at": "2024-01-01T00:00:00Z"
  },
  "message": "Item retrieved successfully"
}

Error Response

{
  "success": false,
  "error": "Item not found",
  "code": "NOT_FOUND",
  "message": "The requested item does not exist"
}

Authentication

Most endpoints require authentication via JWT token in the Authorization header:

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:8000/api/protected-endpoint

Rate Limiting

⚠️ Rate Limits

  • • Anonymous: 10 requests/minute
  • • Authenticated: 30 requests/minute
  • • AI endpoints: 20 requests/minute

Endpoint Categories

🔐 Authentication

User authentication and session management

POST /api/auth/signupPublic
POST /api/auth/signinPublic
POST /api/auth/signoutAuth Required
GET /api/auth/sessionAuth Required

🤖 LLM Integration

AI model interactions and text generation

POST /api/llm/generateAuth Required
POST /api/llm/streamAuth Required
GET /api/llm/modelsAuth Required
GET /api/llm/providersPublic

🔍 Vector Search

Semantic search and embeddings

POST /api/vectors/embedAuth Required
POST /api/vectors/searchAuth Required
POST /api/vectors/storeAuth Required
DELETE /api/vectors/{id}Auth Required

💳 Payments

Subscription and payment processing

POST /api/payments/create-checkoutAuth Required
POST /api/payments/webhookWebhook
GET /api/payments/subscriptionAuth Required
POST /api/payments/cancelAuth Required

Common Patterns

Pagination

# Request with pagination
GET /api/items?page=2&limit=20

# Response includes meta
{
  "success": true,
  "data": [...],
  "meta": {
    "page": 2,
    "limit": 20,
    "total": 145,
    "pages": 8
  }
}

Filtering and Sorting

# Filter by status and sort by date
GET /api/items?status=active&sort=-created_at

# Multiple filters
GET /api/items?status=active&category=tech&min_price=100

Field Selection

# Select specific fields
GET /api/users/123?fields=id,name,email

# Exclude fields
GET /api/users/123?exclude=password,internal_notes

Error Codes

CodeDescriptionHTTP Status
UNAUTHORIZEDMissing or invalid authentication401
FORBIDDENInsufficient permissions403
NOT_FOUNDResource not found404
VALIDATION_ERRORInvalid input data422
RATE_LIMITEDToo many requests429
SERVER_ERRORInternal server error500

Testing Endpoints

Using cURL

# Test authentication
curl -X POST http://localhost:8000/api/auth/signin \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123"}'

# Test with authentication
TOKEN="your-jwt-token"
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/user/profile

Using HTTPie

# More user-friendly alternative to cURL
http POST localhost:8000/api/auth/signin \
  email=test@example.com \
  password=password123

# With auth header
http GET localhost:8000/api/user/profile \
  "Authorization: Bearer $TOKEN"

🚀 API Best Practices

  • Always use HTTPS in production
  • Include proper error messages
  • Version your API when making breaking changes
  • Use consistent naming conventions
  • Implement proper pagination for lists
  • Return appropriate HTTP status codes
  • Document all endpoints thoroughly
  • Validate input data comprehensively
  • Handle errors gracefully
  • Monitor API usage and performance
Back to overview →