# Kelexine.dev REST API: Complete Documentation

**Author:** kelexine  
**Date:** 2025-12-11  
**Category:** Engineering  
**Tags:** API, Documentation, REST, Cloudflare Workers, Reference  
**URL:** https://kelexine.is-a.dev/blog/kelexine-dev-api-documentation

---

## Overview

The Kelexine.dev REST API provides programmatic access to all content on the website, including blog posts, Today I Learned (TIL) entries, and projects. Built on Cloudflare Workers, it offers fast, globally distributed access to content with minimal latency.

**Base URL**: `https://kelexine.is-a.dev/api`

**Authentication**: None required (public API)

**Rate Limiting**: Currently none, but please be respectful

**CORS**: Enabled for all origins

## Response Format

All API responses follow a consistent JSON structure:

### Success Response
```json
{
  "success": true,
  "data": {},
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 50,
    "totalPages": 5
  }
}
```

### Error Response
```json
{
  "success": false,
  "error": "Error message",
  "details": "Additional error details (optional)"
}
```

## Posts API

### List All Posts

**Endpoint**: `GET /api/posts`

**Description**: Retrieve a paginated list of all blog posts

**Parameters**:
- `page` (optional): Page number (default: 1)
- `limit` (optional): Items per page (default: 10, max: 100)
- `category` (optional): Filter by category
- `tag` (optional): Filter by tag
- `q` (optional): Search query (searches title, excerpt, and tags)

**Example Request**:
```bash
curl "https://kelexine.is-a.dev/api/posts?page=2&limit=5&category=AI"
```

**Example Response**:
```json
{
  "success": true,
  "data": [
    {
      "id": "ai-trends-2025",
      "slug": "ai-trends-2025",
      "title": "AI Trends 2025",
      "date": "2025-12-04T00:00:00.000Z",
      "category": "AI",
      "tags": ["AI", "Machine Learning", "Technology"],
      "excerpt": "Exploring the latest trends in AI for 2025...",
      "coverImage": "/images/ai-trends-2025.jpg",
      "author": {
        "name": "kelexine",
        "avatar": "https://avatars.githubusercontent.com/u/70432347?v=4"
      },
      "readTime": "5 min read",
      "headings": [
        {
          "id": "introduction",
          "text": "Introduction",
          "level": 2,
          "index": 1
        }
      ]
    }
  ],
  "meta": {
    "page": 2,
    "limit": 5,
    "total": 12,
    "totalPages": 3
  }
}
```

### Get Single Post

**Endpoint**: `GET /api/posts/:slug`

**Description**: Retrieve detailed information about a specific post

**Parameters**: None (slug is in the URL path)

**Example Request**:
```bash
curl "https://kelexine.is-a.dev/api/posts/ai-trends-2025"
```

**Example Response**:
```json
{
  "success": true,
  "data": {
    "id": "ai-trends-2025",
    "slug": "ai-trends-2025",
    "title": "AI Trends 2025",
    "date": "2025-12-04T00:00:00.000Z",
    "category": "AI",
    "tags": ["AI", "Machine Learning", "Technology"],
    "excerpt": "Exploring the latest trends in AI for 2025...",
    "coverImage": "/images/ai-trends-2025.jpg",
    "author": {
      "name": "kelexine",
      "avatar": "https://avatars.githubusercontent.com/u/70432347?v=4"
    },
    "readTime": "5 min read",
    "headings": [
      {
        "id": "introduction",
        "text": "Introduction",
        "level": 2,
        "index": 1
      },
      {
        "id": "key-trends",
        "text": "Key Trends to Watch",
        "level": 2,
        "index": 2
      }
    ]
  }
}
```

### Filter by Category

**Endpoint**: `GET /api/posts/category/:category`

**Description**: Get all posts in a specific category

**Parameters**:
- `page` (optional): Page number (default: 1)
- `limit` (optional): Items per page (default: 10)

**Example Request**:
```bash
curl "https://kelexine.is-a.dev/api/posts/category/AI?page=1&limit=10"
```

### Filter by Tag

**Endpoint**: `GET /api/posts/tag/:tag`

**Description**: Get all posts with a specific tag

**Parameters**:
- `page` (optional): Page number (default: 1)
- `limit` (optional): Items per page (default: 10)

**Example Request**:
```bash
curl "https://kelexine.is-a.dev/api/posts/tag/React"
```

### Search Posts

**Endpoint**: `GET /api/posts/search`

**Description**: Search posts by title, excerpt, or tags

**Parameters**:
- `q` (required): Search query
- `page` (optional): Page number (default: 1)
- `limit` (optional): Items per page (default: 10)

**Example Request**:
```bash
curl "https://kelexine.is-a.dev/api/posts/search?q=performance"
```

## TIL API

### List All TILs

**Endpoint**: `GET /api/til`

**Description**: Retrieve a paginated list of all TIL entries

**Parameters**:
- `page` (optional): Page number (default: 1)
- `limit` (optional): Items per page (default: 10)
- `tag` (optional): Filter by tag

**Example Request**:
```bash
curl "https://kelexine.is-a.dev/api/til?page=1&limit=5"
```

**Example Response**:
```json
{
  "success": true,
  "data": [
    {
      "id": "curl-time-breakdown",
      "date": "2024-11-23",
      "content": "TIL: Curl can show detailed timing information...",
      "tags": ["CLI", "Debugging", "Performance"],
      "code": {
        "language": "bash",
        "snippet": "curl -w \"timing info\" https://api.example.com"
      },
      "link": "https://curl.se/docs/manpage.html"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 5,
    "total": 15,
    "totalPages": 3
  }
}
```

### Get Single TIL

**Endpoint**: `GET /api/til/:id`

**Description**: Retrieve a specific TIL entry by ID

**Example Request**:
```bash
curl "https://kelexine.is-a.dev/api/til/curl-time-breakdown"
```

### Get Recent TILs

**Endpoint**: `GET /api/til/recent`

**Description**: Get the most recent TIL entries

**Parameters**:
- `count` (optional): Number of entries to return (default: 5, max: 50)

**Example Request**:
```bash
curl "https://kelexine.is-a.dev/api/til/recent?count=10"
```

### Filter TILs by Tag

**Endpoint**: `GET /api/til/tag/:tag`

**Description**: Get all TIL entries with a specific tag

**Parameters**:
- `page` (optional): Page number (default: 1)
- `limit` (optional): Items per page (default: 10)

**Example Request**:
```bash
curl "https://kelexine.is-a.dev/api/til/tag/CLI"
```

## Projects API

### List All Projects

**Endpoint**: `GET /api/projects`

**Description**: Retrieve all projects with optional filtering

**Parameters**:
- `category` (optional): Filter by category
- `featured` (optional): Include only featured projects (add as query param without value)
- `q` (optional): Search query (searches title, description, tech stack, and category)

**Example Request**:
```bash
curl "https://kelexine.is-a.dev/api/projects?category=Frontend&featured"
```

**Example Response**:
```json
{
  "success": true,
  "data": [
    {
      "id": 3,
      "title": "Kelexine Dev Blog",
      "description": "The modern, dark-themed developer blog...",
      "techStack": ["React", "Vite", "Tailwind CSS", "Framer Motion"],
      "githubUrl": "https://github.com/kelexine/kelexine-dev",
      "liveUrl": "https://kelexine.is-a.dev",
      "category": "Frontend",
      "featured": true,
      "date": "2025-12-04",
      "status": "Production"
    }
  ],
  "meta": {
    "total": 1
  }
}
```

### Get Single Project

**Endpoint**: `GET /api/projects/:id`

**Description**: Retrieve detailed information about a specific project

**Example Request**:
```bash
curl "https://kelexine.is-a.dev/api/projects/3"
```

### Get Featured Projects

**Endpoint**: `GET /api/projects/featured`

**Description**: Get all featured projects

**Example Request**:
```bash
curl "https://kelexine.is-a.dev/api/projects/featured"
```

### Filter Projects by Category

**Endpoint**: `GET /api/projects/category/:category`

**Description**: Get all projects in a specific category

**Example Request**:
```bash
curl "https://kelexine.is-a.dev/api/projects/category/Frontend"
```

### Search Projects

**Endpoint**: `GET /api/projects/search`

**Description**: Search projects by title, description, tech stack, or category

**Parameters**:
- `q` (required): Search query

**Example Request**:
```bash
curl "https://kelexine.is-a.dev/api/projects/search?q=React"
```

## Meta API

### List All Categories

**Endpoint**: `GET /api/categories`

**Description**: Get all unique categories from posts

**Example Request**:
```bash
curl "https://kelexine.is-a.dev/api/categories"
```

**Example Response**:
```json
{
  "success": true,
  "data": [
    "AI",
    "Android Dev",
    "CI/CD",
    "Engineering",
    "React",
    "Security",
    "Tutorial",
    "Windows"
  ]
}
```

### List All Tags

**Endpoint**: `GET /api/tags`

**Description**: Get all unique tags from posts and TILs

**Example Request**:
```bash
curl "https://kelexine.is-a.dev/api/tags"
```

**Example Response**:
```json
{
  "success": true,
  "data": [
    "AI",
    "Android",
    "Automation",
    "CLI",
    "Debugging",
    "JavaScript",
    "Machine Learning",
    "Performance",
    "React",
    "Security",
    "Tutorial",
    "TypeScript",
    "Windows"
  ]
}
```

## Error Handling

The API returns appropriate HTTP status codes:

- `200 OK`: Successful request
- `400 Bad Request`: Invalid parameters
- `404 Not Found`: Resource not found
- `500 Internal Server Error`: Server error

Example error response:
```json
{
  "success": false,
  "error": "Post not found"
}
```

## Rate Limiting and Caching

Currently, there are no rate limits on the API. However, please be respectful and implement client-side caching where appropriate.

API responses include cache headers:
- Static data: 1 hour cache
- Dynamic responses: No cache

## Usage Examples

### JavaScript/Fetch
```javascript
// Get all posts
const response = await fetch('https://kelexine.is-a.dev/api/posts');
const data = await response.json();

// Search for AI-related posts
const searchResponse = await fetch('https://kelexine.is-a.dev/api/posts/search?q=AI');
const searchResults = await searchResponse.json();
```

### Python/Requests
```python
import requests

# Get featured projects
response = requests.get('https://kelexine.is-a.dev/api/projects/featured')
projects = response.json()

# Get recent TILs
response = requests.get('https://kelexine.is-a.dev/api/til/recent?count=5')
tils = response.json()
```

### cURL
```bash
# Get posts by category
curl "https://kelexine.is-a.dev/api/posts/category/AI?page=1&limit=5"

# Get specific TIL
curl "https://kelexine.is-a.dev/api/til/curl-time-breakdown"
```

## Integration Ideas

The API can be used for various purposes:

1. **Mobile Apps**: Build a mobile app showcasing the content
2. **RSS Alternatives**: Create custom feeds or notifications
3. **Dashboard Widgets**: Display recent posts or TILs on a dashboard
4. **Content Aggregation**: Include posts in content aggregators
5. **Portfolio Sites**: Showcase projects programmatically
6. **Discord Bots**: Share content in Discord servers
7. **CLI Tools**: Create command-line tools to access content

## Changelog

- **2025-12-11**: Initial API release with all endpoints

## Support

For questions, issues, or feature requests, please contact via the methods listed on the website.

---

*This API documentation is also available as a post on the website. For the latest updates, check the API directly or follow the blog.*

---

*This content is available at [kelexine.is-a.dev/blog/kelexine-dev-api-documentation](https://kelexine.is-a.dev/blog/kelexine-dev-api-documentation)*