Admin Endpoints

Admin Endpoints

Administrative endpoints for managing the Fizzy MCP hosted service. These endpoints require admin-level authentication and are intended for service operators and organization administrators.

Caution

Admin endpoints require elevated permissions. Contact your organization administrator if you need access.

Authentication

Admin endpoints require authentication via API key or admin session:

curl -H "X-API-Key: your-admin-api-key" \
  https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/admin/settings

Alternatively, use an admin session cookie when accessing via browser.

Endpoints

Method	Endpoint	Description
GET	/api/admin/settings	Get all settings
PATCH	/api/admin/settings	Update settings
POST	/api/admin/settings/reset	Reset to defaults
GET	/api/admin/stats/overview	Global usage stats
GET	/api/admin/stats/tools	Per-tool statistics

---

GET /api/admin/settings Admin Only

Retrieves all current service configuration settings.

Request

curl -H "X-API-Key: your-admin-api-key" \
  https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/admin/settings

Response

{
  "data": {
    "service": {
      "name": "Fizzy MCP Hosted",
      "environment": "production",
      "debug": false,
      "maintenanceMode": false
    },
    "rateLimits": {
      "enabled": true,
      "defaultTier": "free",
      "tiers": {
        "free": {
          "requestsPerMinute": 60,
          "dailyLimit": 1000,
          "burstLimit": 10
        },
        "pro": {
          "requestsPerMinute": 300,
          "dailyLimit": 10000,
          "burstLimit": 50
        },
        "enterprise": {
          "requestsPerMinute": 1000,
          "dailyLimit": -1,
          "burstLimit": 100
        }
      }
    },
    "mcp": {
      "toolsEnabled": true,
      "maxConcurrentRequests": 10,
      "timeoutMs": 30000,
      "enabledTools": ["all"]
    },
    "logging": {
      "level": "info",
      "includeRequestBodies": false,
      "retentionDays": 30
    },
    "security": {
      "allowedOrigins": ["*"],
      "requireHttps": true,
      "tokenExpiry": "30d"
    },
    "features": {
      "usageTracking": true,
      "analyticsEnabled": true,
      "webhooksEnabled": false
    }
  },
  "meta": {
    "lastModified": "2024-01-10T15:30:00.000Z",
    "modifiedBy": "admin@example.com",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Settings Categories

Service Settings

Setting	Type	Description
name	string	Service display name
environment	string	production, staging, or development
debug	boolean	Enable debug logging
maintenanceMode	boolean	Enable maintenance mode

Rate Limit Settings

Setting	Type	Description
enabled	boolean	Enable rate limiting
defaultTier	string	Default tier for new users
tiers	object	Per-tier limit configurations

MCP Settings

Setting	Type	Description
toolsEnabled	boolean	Enable MCP tools
maxConcurrentRequests	number	Max concurrent requests per user
timeoutMs	number	Request timeout in milliseconds
enabledTools	array	List of enabled tools (["all"] or specific tool names)

Logging Settings

Setting	Type	Description
level	string	Log level: debug, info, warn, error
includeRequestBodies	boolean	Log request bodies (privacy implications)
retentionDays	number	Days to retain logs

Example

curl

curl -s -H "X-API-Key: your-admin-api-key" \
  "https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/admin/settings" | \
  jq '.data.rateLimits.tiers'

JavaScript

async function getSettings() {
  const response = await fetch(
    'https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/admin/settings',
    { headers: { 'X-API-Key': 'your-admin-api-key' } }
  );

  const { data, meta } = await response.json();

  console.log('=== Service Settings ===');
  console.log(`Environment: ${data.service.environment}`);
  console.log(`Maintenance Mode: ${data.service.maintenanceMode}`);
  console.log(`Last Modified: ${meta.lastModified}`);
  console.log(`Modified By: ${meta.modifiedBy}`);

  return data;
}

getSettings();

---

PATCH /api/admin/settings Admin Only

Updates service configuration settings. Only provided fields are updated; others remain unchanged.

Request

curl -X PATCH \
  -H "X-API-Key: your-admin-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "rateLimits": {
      "tiers": {
        "free": {
          "requestsPerMinute": 100
        }
      }
    },
    "logging": {
      "level": "debug"
    }
  }' \
  https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/admin/settings

Request Body

Provide only the settings you want to update. The structure mirrors the GET response:

{
  "service": {
    "maintenanceMode": true
  },
  "rateLimits": {
    "tiers": {
      "free": {
        "dailyLimit": 2000
      }
    }
  }
}

Response

Returns the complete updated settings:

{
  "data": {
    "service": {
      "name": "Fizzy MCP Hosted",
      "environment": "production",
      "debug": false,
      "maintenanceMode": true
    }
  },
  "meta": {
    "lastModified": "2024-01-15T10:30:00.000Z",
    "modifiedBy": "admin@example.com",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "changes": [
      {
        "path": "service.maintenanceMode",
        "oldValue": false,
        "newValue": true
      },
      {
        "path": "rateLimits.tiers.free.dailyLimit",
        "oldValue": 1000,
        "newValue": 2000
      }
    ]
  }
}

Caution

Changes take effect immediately. Test in staging before applying to production.

Example: Enable Maintenance Mode

curl

# Enable maintenance mode
curl -X PATCH \
  -H "X-API-Key: your-admin-api-key" \
  -H "Content-Type: application/json" \
  -d '{"service": {"maintenanceMode": true}}' \
  "https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/admin/settings"

# Disable maintenance mode

curl -X PATCH \
 -H "X-API-Key: your-admin-api-key" \
 -H "Content-Type: application/json" \
 -d '{"service": {"maintenanceMode": false}}' \
 "https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/admin/settings"

JavaScript

async function updateSettings(updates) {
  const response = await fetch(
    'https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/admin/settings',
    {
      method: 'PATCH',
      headers: {
        'X-API-Key': 'your-admin-api-key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(updates)
    }
  );

  const { data, meta } = await response.json();

  console.log('Settings updated successfully');
  console.log('Changes:');
  meta.changes.forEach(change => {
    console.log(`  ${change.path}: ${change.oldValue} -> ${change.newValue}`);
  });

  return data;
}

// Enable maintenance mode
updateSettings({
  service: { maintenanceMode: true }
});

---

POST /api/admin/settings/reset Admin Only

Resets all settings to their default values. This is a destructive operation.

Request

curl -X POST \
  -H "X-API-Key: your-admin-api-key" \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}' \
  https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/admin/settings/reset

Request Body

Field	Type	Required	Description
confirm	boolean	Yes	Must be true to confirm reset
preserveKeys	array	No	Settings paths to preserve

Example with Preserved Settings

{
  "confirm": true,
  "preserveKeys": ["security.allowedOrigins", "rateLimits.tiers.enterprise"]
}

Response

{
  "data": {
    "reset": true,
    "preservedKeys": ["security.allowedOrigins", "rateLimits.tiers.enterprise"],
    "settings": {
      // Complete default settings
    }
  },
  "meta": {
    "resetAt": "2024-01-15T10:30:00.000Z",
    "resetBy": "admin@example.com",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Danger

This resets ALL settings to defaults. Use preserveKeys to keep critical configurations.

---

GET /api/admin/stats/overview Admin Only

Returns global usage statistics across all users and accounts.

Request

curl -H "X-API-Key: your-admin-api-key" \
  https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/admin/stats/overview

Response

{
  "data": {
    "period": {
      "start": "2024-01-01T00:00:00.000Z",
      "end": "2024-01-15T23:59:59.999Z"
    },
    "totals": {
      "requests": 1547832,
      "reads": 1123456,
      "writes": 424376,
      "errors": 2341,
      "uniqueUsers": 1234,
      "activeAccounts": 89
    },
    "today": {
      "requests": 45678,
      "reads": 32456,
      "writes": 13222,
      "errors": 45,
      "peakHour": 14,
      "peakRpm": 523
    },
    "byTier": {
      "free": {
        "users": 1100,
        "requests": 234567,
        "percentage": 15.2
      },
      "pro": {
        "users": 120,
        "requests": 876543,
        "percentage": 56.6
      },
      "enterprise": {
        "users": 14,
        "requests": 436722,
        "percentage": 28.2
      }
    },
    "topAccounts": [
      {
        "accountId": "acc_xyz789",
        "name": "Acme Corp",
        "requests": 123456,
        "tier": "enterprise"
      },
      {
        "accountId": "acc_abc123",
        "name": "StartupCo",
        "requests": 98765,
        "tier": "pro"
      }
    ],
    "errorBreakdown": {
      "AUTH_ERROR": 1234,
      "RATE_LIMIT_ERROR": 567,
      "VALIDATION_ERROR": 345,
      "NOT_FOUND_ERROR": 123,
      "API_ERROR": 72
    },
    "performance": {
      "avgResponseMs": 45,
      "p50ResponseMs": 32,
      "p95ResponseMs": 89,
      "p99ResponseMs": 156
    }
  },
  "meta": {
    "generatedAt": "2024-01-15T10:30:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Response Fields

Totals Object

Field	Type	Description
requests	number	Total requests in period
reads	number	Read operations
writes	number	Write operations
errors	number	Total errors
uniqueUsers	number	Distinct users
activeAccounts	number	Active accounts

Performance Object

Field	Type	Description
avgResponseMs	number	Average response time
p50ResponseMs	number	50th percentile response time
p95ResponseMs	number	95th percentile response time
p99ResponseMs	number	99th percentile response time

Example: Admin Dashboard

curl

curl -s -H "X-API-Key: your-admin-api-key" \
  "https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/admin/stats/overview" | \
  jq '{
    totalRequests: .data.totals.requests,
    errorRate: ((.data.totals.errors / .data.totals.requests) * 100 | . * 100 | floor / 100 | tostring + "%"),
    topTier: (.data.byTier | to_entries | max_by(.value.requests) | .key),
    avgResponse: (.data.performance.avgResponseMs | tostring + "ms")
  }'

JavaScript

async function getOverview() {
  const response = await fetch(
    'https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/admin/stats/overview',
    { headers: { 'X-API-Key': 'your-admin-api-key' } }
  );

  const { data } = await response.json();

  console.log('=== Service Overview ===\n');
  console.log('Totals:');
  console.log(`  Requests: ${data.totals.requests.toLocaleString()}`);
  console.log(`  Users: ${data.totals.uniqueUsers.toLocaleString()}`);
  console.log(`  Accounts: ${data.totals.activeAccounts}`);

  const errorRate = ((data.totals.errors / data.totals.requests) * 100).toFixed(2);
  console.log(`  Error Rate: ${errorRate}%\n`);

  console.log('Performance:');
  console.log(`  Avg Response: ${data.performance.avgResponseMs}ms`);
  console.log(`  P95 Response: ${data.performance.p95ResponseMs}ms`);
  console.log(`  P99 Response: ${data.performance.p99ResponseMs}ms\n`);

  console.log('Top Accounts:');
  data.topAccounts.slice(0, 5).forEach((acc, i) => {
    console.log(`  ${i + 1}. ${acc.name} (${acc.tier}): ${acc.requests.toLocaleString()}`);
  });
}

getOverview();

---

GET /api/admin/stats/tools Admin Only

Returns detailed per-tool usage statistics for all MCP tools.

Request

curl -H "X-API-Key: your-admin-api-key" \
  https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/admin/stats/tools

Response

{
  "data": {
    "period": {
      "start": "2024-01-01T00:00:00.000Z",
      "end": "2024-01-15T23:59:59.999Z"
    },
    "summary": {
      "totalTools": 40,
      "totalCalls": 1547832,
      "avgCallsPerTool": 38695
    },
    "tools": [
      {
        "name": "fizzy_list_cards",
        "category": "cards",
        "calls": 456789,
        "percentage": 29.5,
        "avgResponseMs": 45,
        "errorRate": 0.12,
        "trend": "+5.2%"
      },
      {
        "name": "fizzy_get_card",
        "category": "cards",
        "calls": 234567,
        "percentage": 15.2,
        "avgResponseMs": 32,
        "errorRate": 0.08,
        "trend": "+2.1%"
      },
      {
        "name": "fizzy_create_card",
        "category": "cards",
        "calls": 123456,
        "percentage": 8.0,
        "avgResponseMs": 89,
        "errorRate": 0.45,
        "trend": "+12.3%"
      },
      {
        "name": "fizzy_list_boards",
        "category": "boards",
        "calls": 98765,
        "percentage": 6.4,
        "avgResponseMs": 28,
        "errorRate": 0.05,
        "trend": "-1.2%"
      }
    ],
    "byCategory": {
      "cards": {
        "tools": 18,
        "calls": 876543,
        "percentage": 56.6,
        "avgResponseMs": 52
      },
      "boards": {
        "tools": 7,
        "calls": 234567,
        "percentage": 15.2,
        "avgResponseMs": 38
      },
      "comments": {
        "tools": 5,
        "calls": 123456,
        "percentage": 8.0,
        "avgResponseMs": 45
      },
      "columns": {
        "tools": 5,
        "calls": 98765,
        "percentage": 6.4,
        "avgResponseMs": 35
      },
      "identity": {
        "tools": 2,
        "calls": 87654,
        "percentage": 5.7,
        "avgResponseMs": 22
      },
      "users": {
        "tools": 2,
        "calls": 76543,
        "percentage": 4.9,
        "avgResponseMs": 25
      },
      "tags": {
        "tools": 1,
        "calls": 50304,
        "percentage": 3.2,
        "avgResponseMs": 18
      }
    },
    "slowestTools": [
      {
        "name": "fizzy_list_cards",
        "p99ResponseMs": 245,
        "avgResponseMs": 45,
        "calls": 456789
      },
      {
        "name": "fizzy_create_card",
        "p99ResponseMs": 198,
        "avgResponseMs": 89,
        "calls": 123456
      }
    ],
    "highestErrorRate": [
      {
        "name": "fizzy_delete_card",
        "errorRate": 2.34,
        "errors": 234,
        "calls": 10000
      },
      {
        "name": "fizzy_update_card",
        "errorRate": 1.23,
        "errors": 1234,
        "calls": 100325
      }
    ]
  },
  "meta": {
    "generatedAt": "2024-01-15T10:30:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Response Fields

Tools Array

Field	Type	Description
name	string	Tool name
category	string	Tool category
calls	number	Total invocations
percentage	number	Percentage of total calls
avgResponseMs	number	Average response time
errorRate	number	Error percentage
trend	string	Week-over-week change

By Category Object

Field	Type	Description
tools	number	Number of tools in category
calls	number	Total calls for category
percentage	number	Percentage of total
avgResponseMs	number	Average response time

Example: Tool Performance Report

curl

# Top 10 most-used tools
curl -s -H "X-API-Key: your-admin-api-key" \
  "https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/admin/stats/tools" | \
  jq '.data.tools[:10] | .[] | "\(.name): \(.calls) calls (\(.percentage)%)"'

# Tools with highest error rates

curl -s -H "X-API-Key: your-admin-api-key" \
 "https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/admin/stats/tools" | \
 jq '.data.highestErrorRate[] | "\(.name): \(.errorRate)% error rate"'

JavaScript

async function getToolStats() {
  const response = await fetch(
    'https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/admin/stats/tools',
    { headers: { 'X-API-Key': 'your-admin-api-key' } }
  );

  const { data } = await response.json();

  console.log('=== Tool Usage Statistics ===\n');
  console.log(`Total Tools: ${data.summary.totalTools}`);
  console.log(`Total Calls: ${data.summary.totalCalls.toLocaleString()}\n`);

  console.log('Top 10 Tools:');
  console.log('-'.repeat(60));
  console.log('Tool'.padEnd(30) + 'Calls'.padStart(12) + '%'.padStart(8) + 'Avg ms'.padStart(10));
  console.log('-'.repeat(60));

  data.tools.slice(0, 10).forEach(tool => {
    console.log(
      tool.name.padEnd(30) +
      tool.calls.toLocaleString().padStart(12) +
      `${tool.percentage}%`.padStart(8) +
      `${tool.avgResponseMs}ms`.padStart(10)
    );
  });

  console.log('\nBy Category:');
  for (const [category, stats] of Object.entries(data.byCategory)) {
    console.log(`  ${category}: ${stats.calls.toLocaleString()} calls (${stats.percentage}%)`);
  }

  console.log('\nSlowest Tools (p99):');
  data.slowestTools.forEach(tool => {
    console.log(`  ${tool.name}: ${tool.p99ResponseMs}ms`);
  });

  console.log('\nHighest Error Rates:');
  data.highestErrorRate.forEach(tool => {
    console.log(`  ${tool.name}: ${tool.errorRate}% (${tool.errors} errors)`);
  });
}

getToolStats();

---

Error Responses

401 Unauthorized

{
  "error": "AUTH_ERROR",
  "message": "Admin authentication required",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

403 Forbidden

{
  "error": "FORBIDDEN_ERROR",
  "message": "Insufficient permissions for admin operations",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

400 Bad Request

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid settings value for 'rateLimits.tiers.free.dailyLimit': must be positive integer or -1",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

---

Security Best Practices

1. Rotate API keys regularly

   Generate new admin API keys every 90 days.

2. Use separate keys for environments

   Never use production admin keys in development or staging.

3. Audit admin actions

   Review the modifiedBy field in settings responses to track changes.

4. Limit admin access

   Only grant admin API keys to team members who require them.

5. Monitor for anomalies

   Set up alerts for unusual admin activity or setting changes.

Next Steps

• REST API Overview - Complete API documentation
• Health Endpoints - Monitor service status
• Usage Endpoints - Track usage statistics