> For the complete documentation index, see [llms.txt](https://project-49.gitbook.io/cashkey/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://project-49.gitbook.io/cashkey/technical-documentation/api.md).

# API Documentation

**CashKey REST API Reference**

Comprehensive RESTful API guide for interacting with the CashKey platform programmatically.

## 🔑 Authentication

### Obtaining API Key

```bash
POST /api/v1/auth/login
Content-Type: application/json

{
  "telegram_id": "123456789",
  "username": "user123"
}
```

### Headers

```
Authorization: Bearer <your_jwt_token>
Content-Type: application/json
```

## 📝 Keys API

### Submit Keys

```bash
POST /api/v1/keys
{
  "title": "AI Trend Analysis",
  "content": "2024 AI market trends...",
  "category": "market_insights",
  "tags": ["AI", "Market", "2024"]
}
```

### Retrieve Keys

```bash
GET /api/v1/keys?limit=10&offset=0&category=market_insights
```

### Check Key Status

```bash
GET /api/v1/keys/{key_id}/status
```

## 👤 User API

### Profile Information

```bash
GET /api/v1/user/profile
```

### Points History

```bash
GET /api/v1/user/points?from=2024-01-01&to=2024-12-31
```

## 📊 Analytics API

### Dashboard Data

```bash
GET /api/v1/analytics/dashboard
```

### Trend Information

```bash
GET /api/v1/analytics/trends?period=7d
```

## 🔗 Webhooks

### Evaluation Complete Notification

```json
{
  "event": "evaluation_completed",
  "key_id": "uuid",
  "score": 145,
  "points_earned": 85,
  "timestamp": "2024-01-01T00:00:00Z"
}
```

## 📋 Response Formats

### Success Response

```json
{
  "success": true,
  "data": { ... },
  "message": "Success"
}
```

### Error Response

```json
{
  "success": false,
  "error": {
    "code": "INVALID_KEY",
    "message": "Key content is invalid"
  }
}
```

## 🚦 Rate Limits

* **Free Tier**: 100 requests/hour
* **Premium**: 1,000 requests/hour
* **Enterprise**: 10,000 requests/hour

***

> 🔧 **SDKs**: Python, JavaScript, Go SDKs coming soon