API Documentation

Comprehensive API reference for Amkyaw.Dev Knowledge Base

Version 1.0.0 RESTful JSON CORS Enabled

Getting Started

Endpoints

External APIs

Code Examples

📖 Introduction

The Amkyaw.Dev Knowledge Base API provides programmatic access to our comprehensive knowledge base. You can search, retrieve categories, and fetch individual knowledge items using simple RESTful endpoints.

Base URL: https://amkyaw.dev/api/v1

Key Features

  • Full-text search across all knowledge items
  • Categorized content organization
  • Related items suggestions
  • Popular and recent items tracking
  • External API integrations (GitHub, OpenAI)

🔐 Authentication

Most endpoints are publicly accessible. For rate-limited or premium endpoints, you'll need an API key.

Using API Key

// Include in headers
headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

To get an API key, contact us or sign up for a developer account.

🌐 Base URL

All API endpoints are relative to this base URL:

https://amkyaw.dev/api/v1
For local development, use: http://localhost:3000/api/v1

⏱️ Rate Limiting

API requests are rate-limited to ensure fair usage:

Plan Requests per minute Requests per day
Public (no key) 10 1,000
Developer (free key) 60 10,000
Premium 300 100,000

Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1625097600

❌ Error Handling

The API uses conventional HTTP response codes:

Code Description
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing API key
404 Not Found - Resource doesn't exist
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error

Error response format:

{
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Too many requests. Please try again later.",
        "details": {
            "limit": 60,
            "reset": 1625097600
        }
    },
    "timestamp": "2024-01-01T12:00:00Z"
}

🔍 Search Knowledge Base

GET /search

Search across all knowledge items with full-text search.

Query Parameters

Parameter Type Required Description
q string Yes Search query (minimum 2 characters)
category string No Filter by category ID
limit integer No Number of results (default: 20, max: 100)
offset integer No Pagination offset (default: 0)
sort string No relevance, date, popularity (default: relevance)

Example Request

curl "https://amkyaw.dev/api/v1/search?q=javascript&category=programming&limit=5"

Example Response

{
    "success": true,
    "data": [
        {
            "id": "js-basics",
            "title": "JavaScript Basics",
            "category": "programming",
            "excerpt": "Learn the fundamentals of JavaScript programming...",
            "relevance": 0.95
        }
    ],
    "pagination": {
        "total": 42,
        "limit": 5,
        "offset": 0,
        "next_offset": 5
    }
}

📂 Get All Categories

GET /categories

Retrieve all available categories with optional item counts.

Query Parameters

Parameter Type Description
include_counts boolean Include item count per category (default: true)
limit integer Maximum categories to return (default: 100)

Example Response

{
    "success": true,
    "data": [
        {
            "id": "general",
            "name": "General Knowledge",
            "description": "Common questions and answers",
            "icon": "📚",
            "item_count": 25,
            "subcategories": ["greetings", "faq", "about"]
        },
        {
            "id": "technical",
            "name": "Technical",
            "description": "Programming and technical topics",
            "icon": "💻",
            "item_count": 42,
            "subcategories": ["programming", "api", "tools"]
        }
    ]
}

📁 Get Single Category

GET /category/{id}

Get detailed information about a specific category.

Path Parameters

Parameter Type Description
id string Category ID (e.g., 'general', 'technical')

Query Parameters

Parameter Type Description
include_items boolean Include items in this category (default: false)
limit integer Number of items to return (default: 50)

Example Request

curl "https://amkyaw.dev/api/v1/category/technical?include_items=true&limit=10"

📄 Get Single Item

GET /item/{id}

Retrieve a specific knowledge item by ID.

Example Response

{
    "success": true,
    "data": {
        "id": "js-closures",
        "title": "JavaScript Closures Explained",
        "category": "programming",
        "content": "A closure is the combination of a function bundled together...",
        "tags": ["javascript", "advanced", "functions"],
        "metadata": {
            "author": "Amkyaw",
            "created": "2024-01-01",
            "updated": "2024-01-15",
            "views": 1234
        },
        "related": ["js-scope", "js-hoisting", "js-prototypes"]
    }
}

🆕 Get Recent Items

GET /recent

Get the most recently added or updated items.

Query Parameters

Parameter Type Description
limit integer Number of items (default: 10, max: 50)

📊 Get Statistics

GET /stats

Get overall knowledge base statistics.

Example Response

{
    "success": true,
    "data": {
        "total_items": 128,
        "total_categories": 5,
        "total_views": 15420,
        "recent_additions": 12,
        "popular_categories": [
            {"name": "Technical", "views": 5234},
            {"name": "General", "views": 4321}
        ],
        "daily_activity": {
            "2024-01-01": 234,
            "2024-01-02": 345
        }
    }
}

❤️ Health Check

GET /health

Check if the API is running and healthy.

Example Response

{
    "status": "healthy",
    "timestamp": "2024-01-01T12:00:00Z",
    "version": "1.0.0",
    "services": {
        "database": "connected",
        "cache": "connected",
        "external_apis": {
            "github": "available",
            "openai": "available"
        }
    }
}

🐙 GitHub Integration

GET /external/github/{username}

Fetch GitHub user profile and repository information.

Example Request

curl "https://amkyaw.dev/api/v1/external/github/amkyaw"

Response Includes

  • User profile information
  • Public repositories
  • Contributions data
  • Languages used

🤖 OpenAI Integration

POST /external/openai

Send prompts to OpenAI's GPT models (requires API key).

Request Body

{
    "prompt": "Explain JavaScript closures in simple terms",
    "model": "gpt-3.5-turbo",
    "max_tokens": 500,
    "temperature": 0.7
}

📝 JavaScript Examples

Using Fetch API

// Search knowledge base
async function searchKnowledge(query) {
    try {
        const response = await fetch(
            `https://amkyaw.dev/api/v1/search?q=${encodeURIComponent(query)}`
        );
        const data = await response.json();
        return data;
    } catch (error) {
        console.error('Search failed:', error);
    }
}

// Using our API Client
const results = await apiClient.search('javascript', {
    category: 'programming',
    limit: 10
});

🐍 Python Examples

import requests

class AmkyawAPI:
    def __init__(self, base_url="https://amkyaw.dev/api/v1"):
        self.base_url = base_url
    
    def search(self, query, category=None, limit=20):
        params = {'q': query, 'limit': limit}
        if category:
            params['category'] = category
        
        response = requests.get(f"{self.base_url}/search", params=params)
        return response.json()
    
    def get_categories(self):
        response = requests.get(f"{self.base_url}/categories")
        return response.json()

# Usage
api = AmkyawAPI()
results = api.search("python programming", limit=5)
categories = api.get_categories()

🔧 cURL Commands

# Search
curl "https://amkyaw.dev/api/v1/search?q=javascript"

# Get categories
curl "https://amkyaw.dev/api/v1/categories"

# Get specific category
curl "https://amkyaw.dev/api/v1/category/technical?include_items=true"

# Get popular items
curl "https://amkyaw.dev/api/v1/popular?limit=5"

# Health check
curl "https://amkyaw.dev/api/v1/health"

📦 SDKs & Libraries

JavaScript/Node.js

Official npm package

npm install amkyaw-api-client
const AmkyawAPI = require('amkyaw-api-client');
const api = new AmkyawAPI('YOUR_API_KEY');

Python

Official PyPI package

pip install amkyaw-api
from amkyaw_api import Client
client = Client(api_key='YOUR_API_KEY')

Need Help?

Try API Playground
Contact Support
GitHub