QCOS API Catalog Documentation

Complete API reference and catalog for QCOS v2.1.0

---

📊 Quick Stats

Metric	Value
Total Endpoints	123
Total Resources	48
Total Modules	16
GET Endpoints	70 (56.9%)
POST Endpoints	45 (36.6%)
DELETE Endpoints	7 (5.7%)
PUT Endpoints	1 (0.8%)

---

📁 Documentation Files

1. QCOS_API_CATALOG.md (Markdown)

• Complete API reference in Markdown format
• All 16 modules documented
• Endpoint details with descriptions
• Authentication and rate limiting info
• Usage examples and SDK support
• Perfect for GitHub, wikis, and documentation sites

Use this for: Detailed documentation, GitHub repos, wiki pages

2. qcos_api_catalog_full.json (JSON)

Structured JSON catalog containing:

{
  "version": "2.1.0",
  "summary": {
    "total_endpoints": 123,
    "total_resources": 48,
    "total_files": 16,
    "methods": {...}
  },
  "endpoints": [...],
  "by_file": {...},
  "by_resource": {...}
}

Use this for: API tooling, automated processing, integrations

3. QCOS_API_CATALOG.html (HTML/Interactive)

• Beautiful interactive dashboard
• Real-time statistics
• Responsive design
• Method distribution charts
• Resource breakdown tables
• Top 25 resources listed

Use this for: Web viewing, presentations, stakeholder reports

---

🎯 How to Use

View HTML Catalog (Recommended)

# Open in your default browser
open docs/QCOS_API_CATALOG.html

# Or with a Python HTTP server
python3 -m http.server -d docs 8000
# Visit http://localhost:8000/QCOS_API_CATALOG.html

Generate Updated Catalog

When endpoints change, regenerate the catalog:

# Generate all formats
python3 scripts/generate_api_catalog.py

# Generate only HTML
python3 scripts/generate_html_catalog.py

Query JSON Data

# View all endpoints by method
cat docs/qcos_api_catalog_full.json | grep '"method"'

# Count endpoints per resource
jq '.by_resource | to_entries[] | "\(.key): \(.value.count)"' docs/qcos_api_catalog_full.json

# List all modules
jq '.by_file | keys[]' docs/qcos_api_catalog_full.json

---

📈 Key Findings

API Characteristics

1. Read-Heavy Design: 56.9% GET endpoints

   • Strong emphasis on data retrieval
   • Optimized for query operations

2. Complex Operations: 36.6% POST endpoints

   • Circuit optimization
   • Job submission
   • Batch processing

3. Immutable Operations: 5.7% DELETE endpoints

   • Careful resource deletion
   • Audit trail maintenance

Top 10 Resources by Endpoint Count

1. jobs (22 endpoints) - Job management and tracking
2. backends (8 endpoints) - Quantum backend configuration
3. providers (6 endpoints) - Cloud provider integration
4. report (6 endpoints) - Reporting and analytics
5. credentials (6 endpoints) - Authentication credentials
6. estimate (5 endpoints) - Cost estimation
7. tenants (4 endpoints) - Multi-tenancy support
8. health (4 endpoints) - System health checks
9. execute (4 endpoints) - Job execution
10. status (3 endpoints) - Status monitoring

Module Distribution

Module	Endpoints	Key Features
network_routes.py	21	Distributed quantum, Phase 0, backends
enhanced.py	18	Core features, optimization, webhooks
ledger_routes.py	15	Budgets, pricing, reports
circuits_v2.py	9	Circuit management
roi_routes_v2.py	9	Business analysis
admin_routes.py	10	System administration
bench.py	8	Performance benchmarking
user_backends_routes.py	8	Custom backends
circuits_resource.py	7	Resource management
azure_quantum_routes.py	7	Azure integration
portal_routes.py	7	User portal
ibm_quantum_routes.py	5	IBM Quantum
braket_routes.py	5	AWS Braket
jobs_v2.py	7	Job management
quantum_macro.py	4	EU Macro optimization
glassbox_routes.py	12	Glass-Box debugging
rerank.py	2	Text reranking
roi_routes.py	4	ROI analysis

---

🔍 Resource Categories

Compute Resources

• jobs (22) - Primary compute resource
• backends (8) - Quantum backend selection
• execute (4) - Job execution

Financial Resources

• estimate (5) - Cost estimation
• pricing - Pricing information
• budgets - Budget management
• credentials (6) - Billing credentials

Admin Resources

• providers (6) - Cloud providers
• tenants (4) - Tenant management
• health (4) - System health
• report (6) - Reporting

Analysis Resources

• benchmarks - Performance metrics
• analytics - Usage analytics
• roi - Return on investment
• market-sizing - Market analysis

---

🔐 API Security

All endpoints require:

• X-License-Key: QuantumLock license header
• Authorization: Bearer token
• Tenant-ID: Multi-tenant isolation (optional)

---

📦 Integration Examples

Automate Catalog Updates

#!/bin/bash
# Update catalog on push
cd /path/to/qcos_server
python3 scripts/generate_api_catalog.py --format all
git add docs/
git commit -m "Update API catalog"
git push

CI/CD Integration

# .github/workflows/catalog.yml
name: Update API Catalog
on: [push]
jobs:
  catalog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - run: python3 scripts/generate_api_catalog.py
      - run: |
          git add docs/
          git commit -m "Auto-update API catalog" || true
          git push

---

🚀 Deployment Status

• Version: 2.1.0-internal
• Status: ✅ Production Live
• Container Images:
  • qcos-api:2.1.0-internal (225 MB)
  • qcos-worker:2.1.0-internal (253 MB)
• Registry: sqtprodacr.azurecr.io
• Protection: Nuitka binary compilation (94 .so files, 0 Python source)

---

📝 Maintenance

When to Regenerate Catalog

1. New endpoints added - Run generate_api_catalog.py
2. Endpoints modified - Regenerate to update documentation
3. Monthly reviews - Ensure catalog stays current
4. Release preparation - Update before version release

How to Extend

Edit scripts/generate_api_catalog.py to:

• Add custom analysis
• Generate additional formats (CSV, PDF)
• Create API usage statistics
• Build interactive documentation

---

📞 Support

• API Docs: https://docs.qcos.io
• GitHub: https://github.com/softquantus/qcos
• Email: support@softquantus.com

---

Generated: January 25, 2026 API Version: v2.1.0 Catalog Version: 1.0.0