> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timepointai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Overview of the Timepoint AI APIs — Gateway, Flash, Clockchain, and Billing.

# API Overview

All consumer traffic goes through the **API Gateway** at `api.timepointai.com`, which authenticates requests, manages credits, enforces rate limits, and proxies to backend services. Each service also has a direct subdomain for service-to-service calls.

## Architecture

```
Client (iPhone, Web App, MCP, etc.)
  │
  ▼
api.timepointai.com  ──>  API Gateway (auth authority, credits, rate limiting, proxy)
  │
  ├── /api/v1/auth/*          ──>  gateway-native (JWT, OAuth, API keys)
  ├── /api/v1/users/*         ──>  gateway-native (user management)
  ├── /api/v1/credits/*       ──>  gateway-native (credit balance, usage)
  ├── /api/v1/clockchain/*    ──>  clockchain.timepointai.com
  ├── /api/v1/billing/*       ──>  billing.timepointai.com
  ├── /api/v1/timepoints/*    ──>  flash.timepointai.com
  ├── /api/v1/* (all else)    ──>  flash.timepointai.com
  └── /health                 ──>  gateway health (native)
```

## Domain Map

| Domain                            | Service        | Auth                                       | Notes                                                                 |
| --------------------------------- | -------------- | ------------------------------------------ | --------------------------------------------------------------------- |
| `api.timepointai.com`             | API Gateway    | Bearer JWT, API keys                       | Auth authority — validates auth, manages credits, proxies to backends |
| `flash.timepointai.com`           | Flash          | Internal only, accessed via Gateway        | Generation engine                                                     |
| `clockchain.timepointai.com`      | Clockchain     | None (public reads) / authenticated writes | Temporal causal graph                                                 |
| `clockchain.timepointai.com/mcp/` | Clockchain MCP | MCP tools (public reads)                   | Streamable HTTP MCP interface (v1.26.0)                               |
| `billing.timepointai.com`         | Billing        | Internal only                              | Credit packs, subscriptions, payment verification                     |

**Consumer apps** (iPhone, web app, external clients) should use `api.timepointai.com` — the gateway authenticates and routes transparently.

**Service-to-service calls** should use direct subdomains (e.g. `clockchain.timepointai.com`) with appropriate service keys to skip the gateway hop.

## Quick Examples

### Clockchain — No Auth Needed

```bash theme={null}
# Get graph stats
curl https://clockchain.timepointai.com/api/v1/stats

# Search moments
curl "https://clockchain.timepointai.com/api/v1/moments?q=rome&limit=5"
```

### Flash — Render a Moment (via Gateway)

```bash theme={null}
curl -X POST https://api.timepointai.com/api/v1/timepoints/generate/sync \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT" \
  -d '{"query": "Moon landing, July 20 1969", "generate_image": true}'
```

## Response Format

All APIs return JSON. Clockchain public endpoints return paginated results:

```json theme={null}
{
  "items": [...],
  "total": 20396,
  "limit": 10,
  "offset": 0
}
```

## Rate Limits

| Tier        | Limit   | Applies To                       |
| ----------- | ------- | -------------------------------- |
| Public      | 60/min  | Clockchain unauthenticated reads |
| Auth reads  | 300/min | Authenticated GET requests       |
| Auth writes | 30/min  | POST/PUT/DELETE with auth        |

Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`

## CORS

All services allow cross-origin requests from `*.timepointai.com` subdomains.