Skip to content

API_GUIDE.md

Latest commit

 

History

History
702 lines (587 loc) · 16 KB

API_GUIDE.md

File metadata and controls

702 lines (587 loc) · 16 KB
Raw

MBTQ Auto-API - Complete API Guide

Table of Contents

  1. Introduction
  2. Authentication
  3. API Endpoints
  4. Code Examples
  5. Error Handling
  6. Rate Limiting

Introduction

The MBTQ Auto-API provides a comprehensive FastAPI backend for discovering, generating, and deploying API integrations. It integrates with three core MBTQ services:

  • 🔐 DeafAUTH: Secure authentication and authorization
  • 🌹 Fibonrose: Activity logging and reputation system
  • ⚡ PinkSync: Automated deployment to mbtq.dev

Authentication

Login

Endpoint: POST /api/auth/login

Request:

{
  "username": "your_username",
  "password": "optional_password"
}

Response:

{
  "success": true,
  "token": "your_auth_token_here",
  "username": "your_username",
  "message": "DeafAUTH authentication successful"
}

Example:

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "developer"}'

Using Authentication

Include the token in the X-MBTQ-Token header for all authenticated endpoints:

curl http://localhost:8000/api/generate \
  -H "X-MBTQ-Token: your_token_here"

API Endpoints

Health & Status

GET /

Root endpoint with API information.

Response:

{
  "name": "MBTQ Auto-API",
  "version": "1.0.0",
  "status": "operational",
  "services": {
    "deafauth": "🔐 Active",
    "fibonrose": "🌹 Active",
    "pinksync": "⚡ Active"
  },
  "docs": "/api/docs"
}

GET /api/health

Health check for all services.

Response:

{
  "status": "healthy",
  "timestamp": "2025-12-14T09:32:45.031Z",
  "services": {
    "deafauth": "healthy",
    "fibonrose": "healthy",
    "pinksync": "healthy"
  }
}

API Discovery

GET /api/entries

Fetch and filter API entries from public-apis.org.

Query Parameters:

  • category (string, optional): Filter by category
  • search (string, optional): Search in API name or description
  • auth (string, optional): Filter by auth type (apiKey, OAuth, X-Mashape-Key)
  • https (boolean, optional): Filter HTTPS-only APIs
  • limit (integer, default: 100): Maximum results to return

Example:

# Get all Development APIs
curl "http://localhost:8000/api/entries?category=Development&limit=10"

# Search for weather APIs
curl "http://localhost:8000/api/entries?search=weather"

# Get APIs requiring API key authentication
curl "http://localhost:8000/api/entries?auth=apiKey"

Response:

[
  {
    "API": "GitHub",
    "Description": "Make requests to the GitHub API",
    "Auth": "apiKey",
    "HTTPS": true,
    "Cors": "yes",
    "Link": "https://api.github.com",
    "Category": "Development"
  }
]

GET /api/categories

Get list of all available categories.

Response:

{
  "categories": ["All", "Animals", "Development", "Finance", ...],
  "count": 50
}

GET /api/github

Get comprehensive GitHub REST API endpoints.

Query Parameters:

  • search (string, optional): Search term to filter GitHub endpoints

Response:

[
  {
    "API": "GitHub - Repositories",
    "Description": "List, create, update, and delete repositories",
    "Auth": "apiKey",
    "HTTPS": true,
    "Cors": "yes",
    "Link": "https://api.github.com/repos",
    "Category": "Development",
    "SubCategory": "GitHub",
    "Endpoints": [
      "GET /repos/{owner}/{repo}",
      "GET /user/repos",
      "GET /orgs/{org}/repos",
      "POST /user/repos",
      "PATCH /repos/{owner}/{repo}",
      "DELETE /repos/{owner}/{repo}"
    ]
  }
]

Available GitHub API Categories:

  • Repositories - Create, read, update, delete repositories
  • Issues - Manage issues, comments, labels, milestones
  • Pull Requests - Create and manage pull requests
  • Commits - Access commit history and details
  • Branches - Manage repository branches
  • Users - Get user information and authentication
  • Organizations - Manage organization accounts and teams
  • Gists - Create and manage code snippets
  • Actions - Manage GitHub Actions workflows and runs
  • Releases - Manage repository releases and assets
  • Search - Search repositories, code, issues, and users
  • Webhooks - Manage repository webhooks and events
  • Contents - Access and modify repository contents
  • Notifications - Manage user notifications
  • Projects - Manage GitHub Projects (project boards)

Example:

# Get all GitHub API endpoints
curl http://localhost:8000/api/github

# Search for specific GitHub APIs
curl "http://localhost:8000/api/github?search=issues"
curl "http://localhost:8000/api/github?search=webhook"

GET /api/enriched

Get curated collection of high-quality open-source and free development APIs.

Query Parameters:

  • search (string, optional): Search in API name or description
  • auth (string, optional): Filter by auth type (apiKey, OAuth, etc.)
  • limit (integer, default: 100): Maximum results to return

Response:

[
  {
    "API": "GitLab API",
    "Description": "Complete REST API for GitLab repositories, CI/CD, and DevOps",
    "Auth": "apiKey",
    "HTTPS": true,
    "Cors": "yes",
    "Link": "https://gitlab.com/api/v4",
    "Category": "Development"
  }
]

Enriched API Categories:

  • Version Control & Code Hosting: GitLab, Bitbucket
  • Package Registries: npm, PyPI, crates.io, Maven Central
  • Code Quality & Analysis: SonarQube, Codacy
  • CI/CD & Deployment: CircleCI, Travis CI, Vercel, Netlify
  • Documentation & Knowledge: Stack Exchange, DevDocs
  • Container & Cloud: Docker Hub, Heroku
  • API Development & Testing: Postman, Swagger/OpenAPI, JSONPlaceholder, ReqRes
  • Code Collaboration: Slack, Discord
  • Project Management: Jira, Trello, Linear
  • Analytics & Monitoring: Google Analytics, Sentry
  • Security & Vulnerability: CVE Details, Snyk
  • AI & Machine Learning: OpenAI, Hugging Face
  • Data & Database: JSONbin.io, Supabase
  • Utilities & Tools: REST Countries, IP API, QR Code Generator, UUID Generator

Example:

# Get all enriched APIs
curl http://localhost:8000/api/enriched

# Search for specific APIs
curl "http://localhost:8000/api/enriched?search=docker"
curl "http://localhost:8000/api/enriched?search=npm"

# Filter by authentication type
curl "http://localhost:8000/api/enriched?auth=apiKey&limit=10"

# Get APIs without authentication
curl "http://localhost:8000/api/enriched?auth="

GET /api/curated

Get all curated APIs (GitHub REST API + enriched development APIs combined).

Query Parameters:

  • include_github (boolean, default: true): Include GitHub endpoints
  • include_enriched (boolean, default: true): Include enriched APIs
  • search (string, optional): Search term
  • limit (integer, default: 200): Maximum results to return

Response:

[
  {
    "API": "GitHub - Repositories",
    "Description": "List, create, update, and delete repositories",
    "Auth": "apiKey",
    "HTTPS": true,
    "Cors": "yes",
    "Link": "https://api.github.com/repos",
    "Category": "Development",
    "SubCategory": "GitHub",
    "Endpoints": [...]
  },
  {
    "API": "GitLab API",
    "Description": "Complete REST API for GitLab repositories, CI/CD, and DevOps",
    "Auth": "apiKey",
    "HTTPS": true,
    "Cors": "yes",
    "Link": "https://gitlab.com/api/v4",
    "Category": "Development"
  }
]

Example:

# Get all curated APIs (GitHub + enriched)
curl http://localhost:8000/api/curated

# Get only GitHub APIs
curl "http://localhost:8000/api/curated?include_enriched=false"

# Get only enriched APIs
curl "http://localhost:8000/api/curated?include_github=false"

# Search across all curated APIs
curl "http://localhost:8000/api/curated?search=api&limit=50"

Code Generation

POST /api/generate

Generate full-stack code for API integration.

Authentication: Required (X-MBTQ-Token header)

Request Body:

{
  "api_name": "GitHub",
  "description": "GitHub REST API",
  "link": "https://api.github.com",
  "category": "Development",
  "auth": "apiKey",
  "https": true
}

Response:

{
  "success": true,
  "code": "// Full-stack code here...",
  "api_name": "GitHub",
  "generated_at": "2025-12-14T09:32:45.031Z",
  "mbtq_metadata": {
    "deafauth": "✅ Validated",
    "fibonrose": "🌹 Logged",
    "pinksync": "⚡ Ready"
  }
}

Generated Code Includes:

  • FastAPI backend endpoint
  • React frontend component
  • Vercel deployment configuration
  • Requirements.txt
  • Documentation

Example:

curl -X POST http://localhost:8000/api/generate \
  -H "Content-Type: application/json" \
  -H "X-MBTQ-Token: YOUR_TOKEN" \
  -d '{
    "api_name": "GitHub",
    "description": "GitHub REST API",
    "link": "https://api.github.com",
    "category": "Development",
    "auth": "apiKey",
    "https": true
  }'

Deployment

POST /api/deploy

Deploy generated API to mbtq.dev via PinkSync.

Authentication: Required (X-MBTQ-Token header)

Request Body:

{
  "api_name": "GitHub",
  "code": "// Generated code...",
  "config": {
    "name": "mbtq-github-api",
    "env_vars": {
      "API_KEY": "optional"
    }
  }
}

Response:

{
  "success": true,
  "deployment_id": "uuid-here",
  "url": "https://mbtq.dev/api/github",
  "status": "deployed",
  "logs": [
    {
      "timestamp": "09:32:45",
      "message": "🚀 PinkSync: Initiating deployment...",
      "type": "info"
    },
    {
      "timestamp": "09:32:50",
      "message": "✅ Live at: https://mbtq.dev/api/github",
      "type": "success"
    }
  ],
  "deployed_at": "2025-12-14T09:32:45.031Z"
}

Example:

curl -X POST http://localhost:8000/api/deploy \
  -H "Content-Type: application/json" \
  -H "X-MBTQ-Token: YOUR_TOKEN" \
  -d '{
    "api_name": "GitHub",
    "code": "YOUR_GENERATED_CODE"
  }'

GET /api/deployments/{deployment_id}

Get deployment status by ID.

Authentication: Required (X-MBTQ-Token header)

Response:

{
  "deployment_id": "uuid-here",
  "api_name": "GitHub",
  "url": "https://mbtq.dev/api/github",
  "status": "deployed",
  "created_at": "2025-12-14T09:32:45.031Z",
  "updated_at": "2025-12-14T09:32:50.031Z"
}

Fibonrose - Activity Logs

GET /api/fibonrose/logs

Get activity logs for authenticated user.

Authentication: Required (X-MBTQ-Token header)

Query Parameters:

  • limit (integer, default: 50): Maximum logs to return

Response:

{
  "logs": [
    {
      "id": "uuid",
      "action": "code_generation_completed",
      "metadata": {
        "api_name": "GitHub",
        "code_length": 7030
      },
      "user": "developer",
      "timestamp": "2025-12-14T09:32:45.031Z",
      "reputation_impact": 20
    }
  ],
  "count": 10,
  "user": "developer"
}

Example:

curl http://localhost:8000/api/fibonrose/logs?limit=10 \
  -H "X-MBTQ-Token: YOUR_TOKEN"

Fibonrose - Reputation

GET /api/fibonrose/reputation

Get user's reputation score and level.

Authentication: Required (X-MBTQ-Token header)

Response:

{
  "username": "developer",
  "score": 150,
  "level": "Apprentice",
  "total_actions": 25,
  "last_activity": "2025-12-14T09:32:45.031Z",
  "recent_history": [
    {
      "action": "deployment_completed",
      "impact": 50,
      "timestamp": "2025-12-14T09:32:45.031Z"
    }
  ]
}

Reputation Levels:

  • Novice: 0-49 points
  • Apprentice: 50-149 points
  • Adept: 150-299 points
  • Expert: 300-499 points
  • Master: 500-999 points
  • Grandmaster: 1000+ points

Reputation Points:

Action Points
Authentication +5
API Entries Fetch +1
Code Generation Started +10
Code Generation Completed +20
Deployment Started +15
Deployment Completed +50
Authentication Error -5
Code Generation Error -10
Deployment Error -25

Code Examples

Python

import httpx
import asyncio

async def use_mbtq_api():
    base_url = "http://localhost:8000"
    
    async with httpx.AsyncClient() as client:
        # Authenticate
        response = await client.post(
            f"{base_url}/api/auth/login",
            json={"username": "developer"}
        )
        token = response.json()["token"]
        
        # Generate code
        response = await client.post(
            f"{base_url}/api/generate",
            headers={"X-MBTQ-Token": token},
            json={
                "api_name": "GitHub",
                "description": "GitHub REST API",
                "link": "https://api.github.com",
                "category": "Development",
                "auth": "apiKey",
                "https": True
            }
        )
        code = response.json()["code"]
        
        # Deploy
        response = await client.post(
            f"{base_url}/api/deploy",
            headers={"X-MBTQ-Token": token},
            json={"api_name": "GitHub", "code": code}
        )
        url = response.json()["url"]
        print(f"Deployed to: {url}")

asyncio.run(use_mbtq_api())

JavaScript

const axios = require('axios');

async function useMBTQAPI() {
  const baseURL = 'http://localhost:8000';
  
  // Authenticate
  const authResponse = await axios.post(`${baseURL}/api/auth/login`, {
    username: 'developer'
  });
  const token = authResponse.data.token;
  
  // Generate code
  const genResponse = await axios.post(
    `${baseURL}/api/generate`,
    {
      api_name: 'GitHub',
      description: 'GitHub REST API',
      link: 'https://api.github.com',
      category: 'Development',
      auth: 'apiKey',
      https: true
    },
    {
      headers: { 'X-MBTQ-Token': token }
    }
  );
  const code = genResponse.data.code;
  
  // Deploy
  const deployResponse = await axios.post(
    `${baseURL}/api/deploy`,
    { api_name: 'GitHub', code },
    {
      headers: { 'X-MBTQ-Token': token }
    }
  );
  console.log(`Deployed to: ${deployResponse.data.url}`);
}

useMBTQAPI();

cURL

# 1. Authenticate
TOKEN=$(curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "developer"}' | jq -r '.token')

# 2. Generate code
CODE=$(curl -X POST http://localhost:8000/api/generate \
  -H "Content-Type: application/json" \
  -H "X-MBTQ-Token: $TOKEN" \
  -d '{
    "api_name": "GitHub",
    "description": "GitHub REST API",
    "link": "https://api.github.com",
    "category": "Development",
    "auth": "apiKey",
    "https": true
  }' | jq -r '.code')

# 3. Deploy
curl -X POST http://localhost:8000/api/deploy \
  -H "Content-Type: application/json" \
  -H "X-MBTQ-Token: $TOKEN" \
  -d "{\"api_name\": \"GitHub\", \"code\": $(echo $CODE | jq -R .)}"

Error Handling

All errors follow a consistent format:

{
  "error": "Error message here",
  "timestamp": "2025-12-14T09:32:45.031Z",
  "path": "/api/endpoint"
}

Common HTTP Status Codes

  • 200 OK: Request successful
  • 401 Unauthorized: Missing or invalid DeafAUTH token
  • 404 Not Found: Resource not found
  • 422 Unprocessable Entity: Invalid request body
  • 500 Internal Server Error: Server error
  • 502 Bad Gateway: External service unavailable

Example Error Response

{
  "error": "DeafAUTH token required",
  "timestamp": "2025-12-14T09:32:45.031Z",
  "path": "/api/generate"
}

Rate Limiting

The API implements rate limiting to ensure fair usage:

  • Default: 60 requests per minute per user
  • Headers included in responses:
    • X-RateLimit-Limit: Maximum requests per window
    • X-RateLimit-Remaining: Remaining requests
    • X-RateLimit-Reset: Time when limit resets

Interactive Documentation

FastAPI provides automatic interactive documentation:

These interfaces allow you to:

  • Browse all endpoints
  • View request/response schemas
  • Test endpoints directly in the browser
  • Download OpenAPI specification

Support

For issues, questions, or contributions:

Made with ❤️ by the MBTQ Team