API Overview¶

Armory Bot provides a RESTful API for accessing bot data and statistics programmatically.

Introduction¶

The Armory Bot API allows you to: - Monitor bot health and status - Retrieve statistics across all servers - Access command information - Query server data - Build dashboards and integrations

Getting Started¶

Base URL¶

http://localhost:8001/api

Note: Replace with your deployed API URL in production.

Quick Start¶

Check if the API is running:

curl http://localhost:8001/

Expected response:

{
  "message": "Armory Bot API",
  "version": "1.0.0",
  "status": "operational"
}

Authentication¶

Currently, the API is public and read-only. No authentication required.

Future Plans: API keys for authenticated requests and write operations.

Rate Limiting¶

All endpoints have rate limits to prevent abuse. See Rate Limits for details.

Available Endpoints¶

Core Endpoints¶

Endpoint	Method	Description	Rate Limit
`/`	GET	API information	None
`/api/health`	GET	Health check	None
`/api/stats`	GET	Bot statistics	30/min
`/api/commands`	GET	Command list	10/min
`/api/guilds`	GET	Server information	5/min

Documentation¶

For detailed endpoint documentation, see: - Endpoints Reference - Complete API documentation - Rate Limits - Rate limiting details - Examples - Integration examples

Response Format¶

Success Response¶

{
  "data": { ... },
  "status": "success"
}

Error Response¶

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "status": "error"
}

Status Codes¶

Code	Meaning
200	Success
400	Bad Request
404	Not Found
429	Rate Limit Exceeded
500	Internal Server Error
503	Service Unavailable

CORS¶

The API supports CORS for browser-based applications:

Allowed Origins: - http://localhost:3000 - http://localhost:8000 - http://localhost:8001

Methods: GET, POST, OPTIONS

Quick Examples¶

Check Health¶

curl http://localhost:8001/api/health

Get Statistics¶

curl http://localhost:8001/api/stats

List Commands¶

curl http://localhost:8001/api/commands

Filter by Category¶

curl "http://localhost:8001/api/commands?category=economy"

Integration Libraries¶

JavaScript/TypeScript¶

const API_BASE = 'http://localhost:8001/api';

async function getStats() {
  const response = await fetch(`${API_BASE}/stats`);
  return await response.json();
}

Python¶

import requests

API_BASE = 'http://localhost:8001/api'

def get_stats():
    response = requests.get(f'{API_BASE}/stats')
    return response.json()

Best Practices¶

Cache Responses - Cache data when possible to reduce API calls
Handle Rate Limits - Implement exponential backoff for 429 responses
Error Handling - Always handle network and API errors gracefully
Use Pagination - For large datasets, use limit/offset parameters
Monitor Health - Regularly check /api/health for service status

Use Cases¶

Dashboard¶

Build a web dashboard showing: - Bot statistics (guilds, users, uptime) - Command usage - Server list - Real-time health status

Monitoring¶

Create monitoring tools to: - Track bot uptime - Alert on service issues - Monitor resource usage - Track growth metrics

Integration¶

Integrate with other services: - Website statistics display - Discord webhooks for status updates - Third-party dashboards - Mobile applications

Changelog¶

Version 1.0.0 (Current)¶

Features: - Health check endpoint - Statistics endpoint - Commands list endpoint - Guilds information endpoint - Rate limiting - CORS support

Upcoming: - API authentication - Write endpoints - Webhooks - Real-time WebSocket connections

Support¶

Documentation: - Endpoints - Rate Limits - Examples

Help: - Support Server - GitHub Issues - API Status Page

Ready to get started? Check out the Endpoints Reference for complete API documentation.