API Design

Gap Closure: B1.2

This page addresses Blueprint Supplement Gap B1.2: "No API design or data schema yet." This is a proposed API design requiring CTO review before implementation. All endpoints, schemas, and patterns described here are recommendations.

Executive Summary

The ReGenesis API is the single point of entry for all client applications (web, mobile, browser extension) and external integrations. It is a RESTful API with versioning, JWT authentication, role-based authorization, rate limiting, and comprehensive audit logging.

API at a Glance

Attribute	Specification
Protocol	HTTPS (TLS 1.3)
Style	RESTful with JSON payloads
Versioning	URL-based (/api/v1/)
Authentication	JWT with refresh token rotation
Authorization	RBAC + ABAC (visibility tags)
Rate Limiting	Per-tenant, per-user, per-endpoint
Pagination	Cursor-based for lists
Error Format	RFC 7807 (Problem Details)
Documentation	OpenAPI 3.1 spec
Monitoring	Request logging, latency tracking, error rates

Endpoint Groups

Group	Purpose	Key Endpoints
/auth	Authentication and session management	Login, refresh, logout, MFA
/users	User profile management	CRUD, preferences, consent
/sessions	Coaching session management	Schedule, metadata, recordings
/relationships	Coach-coachee relationship management	List, create, update status, end
/goals	Goal tracking and progress	CRUD, linked evidence, archival
/action-items	Action item management	CRUD, filter by session/goal/status
/transcripts	Session transcript access	View, search
/insights	AI-generated insights	List, detail, approve, reject
/evidence	Evidence pack access	L0/L1/L2, provenance
/integrations	Third-party connections	Connect, disconnect, status
/uploads	File upload management	Presigned URL, confirm upload
/sasha	Sasha AI interactions	Companion chat, live session
/admin	Tenant administration	Users, settings, metrics
/webhooks	Incoming webhook receivers	Zoom, Stripe, Slack, Teams

Working Knowledge

API Design Principles

1. Everything Goes Through the API

No client application accesses the database directly. Web, mobile, and browser extension all use the same API. This ensures consistent security enforcement.

2. Tenant Isolation at the Gateway

The API gateway extracts the tenant ID from the JWT token and sets it for every database query. No request can access another tenant's data.

3. Visibility Filtering is Automatic

When a coachee requests insights, the API automatically filters to client_visible only. When a coach requests the same endpoint, they also see coach_only. This is handled by middleware -- the endpoint code does not need to check visibility manually.

4. No Content in URLs

Session content, coaching data, and PII are NEVER included in URL paths or query parameters (which could be logged). They travel in request/response bodies only.

5. Cursor-Based Pagination

All list endpoints use cursor-based pagination for consistent performance and real-time data safety (no offset-based page skipping that breaks when data changes).

How Authentication Works

1. Login: User sends email + password to /api/v1/auth/login
2. MFA Challenge: If MFA is enabled, server responds with a challenge; user sends TOTP code to /api/v1/auth/mfa/verify
3. Tokens Issued: Server returns an access token (30 min) and refresh token (7 days)
4. Subsequent Requests: Client includes Authorization: Bearer {access_token} header
5. Token Refresh: Before access token expires, client calls /api/v1/auth/refresh with the refresh token
6. Refresh Rotation: Each refresh returns a new refresh token (the old one is invalidated)
7. Logout: Client calls /api/v1/auth/logout which invalidates all tokens

Rate Limiting

Rate limits protect against abuse and cost overruns:

Tier	Limit	Scope
Global	1000 req/min per tenant	All endpoints
Auth	10 req/min per IP	Login, register, password reset
AI	20 req/min per user	Sasha companion, insight generation
Integration	30 req/min per provider	External API calls
Admin	100 req/min per user	Admin endpoints

When rate limited, the API returns 429 Too Many Requests with a Retry-After header.

Error Handling

All errors follow RFC 7807 (Problem Details for HTTP APIs):

{
  "type": "https://docs.regenesis.ai/errors/insufficient-consent",
  "title": "Consent Required",
  "status": 403,
  "detail": "This action requires 'sasha_analyze' consent which has not been granted.",
  "instance": "/api/v1/insights/generate",
  "consentUrl": "/api/v1/consent/sasha_analyze"
}

Technical Spec

---

Request Flow Diagram

---

No PII in URLs

Query parameters and URL paths are logged by CDNs, load balancers, and web servers. NEVER include coaching content, user names, email addresses, or any PII in URLs. All sensitive data travels in request/response bodies over HTTPS.

API Key Rotation

Service-to-service API keys must be rotated every 90 days. The rotation process must be automated and zero-downtime (dual-key validation during transition period).

OpenAPI Specification

A full OpenAPI 3.1 specification will be generated from the TypeScript interfaces above and published at https://docs.regenesis.ai/api/v1/openapi.json. This enables automated client SDK generation and API testing.