# API Directory - Documentation

This directory contains **static files** for the Claude Code Templates project deployed on Vercel.

## 📁 Structure Overview

```
docs/api/
├── README.md     # This file
└── agents.json   # Static JSON file for agent queries
```

## 🔍 Why This Structure?

The project uses **TWO separate API directories**:

### 1. `/api/` (Root) - Serverless Functions ✅
```
/api/
├── track-download-supabase.js     # Serverless function
└── package.json                   # Dependencies
```

- **Purpose:** Vercel serverless functions (Edge Functions)
- **Auto-detected by Vercel:** Functions in `/api/` are automatically deployed
- **Runtime:** Node.js with ES Modules
- **URL:** `https://www.aitmpl.com/api/track-download-supabase`

### 2. `/docs/api/` - Static Files ✅
```
/docs/api/
├── README.md      # This documentation
└── agents.json    # Static data file
```

- **Purpose:** Static JSON files served with the frontend
- **Served from:** `outputDirectory: "docs"` in `vercel.json`
- **URL:** `https://www.aitmpl.com/api/agents.json`

## ⚠️ Important: Why Two Directories?

Vercel has a specific requirement:
- **Serverless functions MUST be in `/api/`** at the project root
- **Static files can be in `/docs/api/`** when using `outputDirectory: "docs"`

You **cannot** put serverless functions in `/docs/api/` - Vercel will serve them as static HTML files instead of executing them.

---

## 📄 Files in This Directory

### `agents.json` (Static File)
- **Type:** Static JSON data
- **Purpose:** Contains the list of available agents for the frontend
- **Accessed by:** Frontend application via fetch
- **URL:** `https://www.aitmpl.com/api/agents.json`
- **Size:** ~25KB
- **Updates:** Generated by `/scripts/generate_components_json.py` script

**Usage:**
```javascript
fetch('https://www.aitmpl.com/api/agents.json')
  .then(res => res.json())
  .then(data => console.log(data));
```

---

## 🔗 Related Files

### Serverless Functions (in `/api/`)

See `/api/README.md` for documentation on:
- `track-download-supabase.js` - Download tracking endpoint
- Environment variables required
- Request/response formats
- Database schema

---

## 📝 Best Practices

1. **Static Files:** Keep in `/docs/api/`
2. **Serverless Functions:** Keep in `/api/` (root)
3. **Never Mix:** Don't put serverless functions in `/docs/api/`
4. **Version Control:** Commit both directories separately

---

**Last Updated:** October 22, 2025
**Maintained by:** Claude Code Templates Team