API Reference

Quick Links

Documentation Dashboard Support

Base URL

https://speedthings.com/api

SpeedThings API Reference

REST API v1.0 - Build powerful integrations with SpeedThings performance optimization platform and MCP agents.

Base URL

https://speedthings.com/api

Current Version

v1.0

Key Features

MCP Agent Management

Enable, configure, and monitor AI agents

Performance Testing

Automated speed tests and monitoring

Analytics & Insights

Detailed performance metrics and trends

Authentication

SpeedThings API uses session-based authentication for web applications and API key authentication for server-to-server integrations.

Session Authentication

Used automatically when accessing the API from the SpeedThings dashboard or after logging in.

Request Example 
GET /api/mcp/agents/active
Host: speedthings.com
Cookie: connect.sid=s%3A...

API Key Authentication

Generate API keys in your dashboard for server-to-server integrations.

Request Example 
GET /api/mcp/agents/active
Host: speedthings.com
Authorization: Bearer st_live_key_...

Security Note

Keep your API keys secure. Never expose them in client-side code or public repositories.

Rate Limits

Professional Plan

  • 1,000 requests per hour
  • 50 burst requests
  • 10 concurrent requests

Business Plan

  • 5,000 requests per hour
  • 100 burst requests
  • 25 concurrent requests

Rate Limit Headers

Response Headers 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
X-RateLimit-Retry-After: 3600

Free Tools API

Access SpeedThings' free optimization tools programmatically. These endpoints are available to all registered users.

POST /api/tools/ai-chat

Get AI-powered assistance for performance optimization and development questions.

Request Body

{
  "message": "How can I optimize my website's loading speed?",
  "context": {
    "url": "https://example.com",
    "currentScore": 65
  }
}

Response Example

{
  "success": true,
  "response": {
    "message": "Here are 5 key ways to improve your website's loading speed...",
    "suggestions": [
      "Optimize images and convert to WebP format",
      "Enable gzip compression",
      "Minify CSS and JavaScript files",
      "Use a Content Delivery Network (CDN)",
      "Optimize database queries"
    ],
    "priority": "high",
    "estimatedImpact": "+15-25 points"
  }
}
POST /api/tools/seo-quick-check

Perform instant SEO analysis on any website with actionable recommendations.

Request Body

{
  "url": "https://example.com",
  "checkMobile": true,
  "includeKeywords": false
}

Response Example

{
  "success": true,
  "results": {
    "score": 78,
    "title": {
      "present": true,
      "length": 52,
      "recommendation": "Good length"
    },
    "metaDescription": {
      "present": true,
      "length": 145
    },
    "headings": {
      "h1Count": 1,
      "structure": "good"
    },
    "recommendations": [
      "Add alt text to 3 images",
      "Improve page loading speed"
    ]
  }
}
POST /api/tools/optimize-image

Upload and optimize images with automatic compression and format conversion.

Request Format

Content-Type: multipart/form-data

  • image: File (required) - Image file to optimize
  • quality: Integer (optional) - Compression quality 0-100, default: 80
  • format: String (optional) - Output format: webp, jpeg, png
  • maxWidth: Integer (optional) - Maximum width in pixels

cURL Example

curl -X POST "https://speedthings.com/api/tools/optimize-image" \
  -H "Authorization: Bearer your-api-key" \
  -F "image=@/path/to/image.jpg" \
  -F "quality=85" \
  -F "format=webp"

Response Example

{
  "success": true,
  "optimization": {
    "originalSize": "2.4MB",
    "optimizedSize": "480KB",
    "savings": "80%",
    "format": "webp",
    "dimensions": {
      "width": 800,
      "height": 600
    }
  },
  "downloadUrl": "https://speedthings.com/optimized/abc123.webp",
  "expiresAt": "2025-01-16T10:30:00Z"
}

Performance API

Comprehensive performance testing and monitoring tools available to all verified users.

POST /api/tools/website-speed-test

Run comprehensive speed tests with Core Web Vitals analysis and optimization recommendations.

Request Body

{
  "url": "https://example.com",
  "device": "desktop",
  "location": "us-east",
  "includeScreenshot": true,
  "analyzeResources": true
}

Parameters

  • device: desktop, mobile, tablet
  • location: us-east, eu-west, asia
  • includeScreenshot: boolean
  • analyzeResources: boolean

Response Example

{
  "success": true,
  "results": {
    "score": 87,
    "loadTime": 2.34,
    "pageSize": "2.1MB",
    "coreWebVitals": {
      "lcp": 1.8,
      "fid": 45,
      "cls": 0.12,
      "fcp": 1.2,
      "ttfb": 450
    },
    "metrics": {
      "totalRequests": 42,
      "totalSize": "2.1MB",
      "gzipSavings": "30%"
    },
    "recommendations": [
      {
        "type": "image_optimization",
        "description": "Optimize images for better compression",
        "impact": "high",
        "savings": "1.2MB"
      },
      {
        "type": "text_compression",
        "description": "Enable text compression",
        "impact": "medium",
        "savings": "200KB"
      }
    ],
    "screenshot": "https://speedthings.com/screenshots/abc123.png"
  }
}
POST /api/tools/seo-check

Analyze how page speed affects SEO with Google PageSpeed insights integration.

Request Body

{
  "url": "https://example.com",
  "includeKeywords": true,
  "mobileAnalysis": true,
  "competitors": ["competitor1.com"]
}

Response Example

{
  "success": true,
  "seo": {
    "speedScore": 78,
    "seoScore": 85,
    "mobileScore": 72,
    "recommendations": [
      "Improve Largest Contentful Paint",
      "Reduce unused JavaScript"
    ],
    "keywordAnalysis": {
      "density": "2.3%",
      "mainKeywords": ["optimization", "speed"]
    }
  }
}
POST /api/tools/start-monitoring

Set up continuous performance monitoring with custom alert thresholds.

Request Body

{
  "url": "https://example.com",
  "interval": "5m",
  "alerts": {
    "scoreThreshold": 80,
    "loadTimeThreshold": 3.0,
    "webhookUrl": "https://your-app.com/webhook"
  },
  "locations": ["us-east", "eu-west"]
}

Get Monitoring Data

GET /api/tools/monitoring-data/:domain?days=7

Response Format

{
  "success": true,
  "monitoring": {
    "status": "active",
    "interval": "5m",
    "lastCheck": "2025-01-15T10:25:00Z",
    "uptime": "99.8%",
    "avgScore": 85,
    "avgLoadTime": 2.1
  }
}

MCP Agents API

Manage Model Context Protocol agents programmatically. Enable, configure, and monitor your AI-powered integrations.

GET /api/mcp/agents/available

List all MCP agents available for your subscription plan.

Query Parameters

Parameter Type Description
plan string Optional. Filter by plan (professional, business)
category string Optional. Filter by category (automation, monitoring, etc.)

Request Example

curl -X GET "https://speedthings.com/api/mcp/agents/available?plan=professional" \
  -H "Authorization: Bearer st_live_key_..."

Response Example

{
  "success": true,
  "agents": {
    "zapier-integration": {
      "id": "zapier-integration",
      "name": "Zapier Integration",
      "description": "Connect to 7,000+ apps...",
      "category": "automation",
      "requiredPlan": "professional",
      "features": [
        "Connect to Slack, Google Workspace",
        "Automated workflow triggers"
      ]
    }
  },
  "categories": {
    "automation": {
      "name": "Automation",
      "icon": "fas fa-robot"
    }
  }
}
POST /api/mcp/agents/enable

Enable an MCP agent with optional configuration.

Request Body

{
  "agentId": "zapier-integration",
  "configuration": {
    "api_key": "your-zapier-key",
    "webhook_url": "https://hooks.zapier.com/...",
    "triggers": ["performance_degradation"]
  }
}

Response

{
  "success": true,
  "result": {
    "agentId": "zapier-integration",
    "enabled": true,
    "configurationValid": true
  }
}
GET /api/mcp/agents/{agentId}/stats

Get usage statistics for a specific agent.

Path Parameters

agentId - The unique identifier of the agent

Request Example

curl -X GET "https://speedthings.com/api/mcp/agents/zapier-integration/stats?days=7" \
  -H "Authorization: Bearer st_live_key_..."

Response Example

{
  "success": true,
  "stats": {
    "total_calls": 156,
    "successful_calls": 154,
    "avg_response_time": 245,
    "success_rate": 0.987,
    "last_used": "2025-01-15T10:30:00Z"
  }
}

Performance API

Trigger performance tests, retrieve results, and monitor website speed metrics programmatically.

POST /api/tools/website-speed-test

Run a comprehensive speed test on any URL.

Request Body

{
  "url": "https://example.com",
  "device": "desktop",
  "location": "us-east"
}

Response Example

{
  "success": true,
  "results": {
    "score": 87,
    "loadTime": 2.34,
    "pageSize": "2.1MB",
    "coreWebVitals": {
      "lcp": 1.8,
      "fid": 45,
      "cls": 0.12
    },
    "recommendations": [
      "Optimize images for better compression",
      "Enable text compression"
    ]
  }
}

Webhooks

Configure webhooks to receive real-time notifications about performance changes, agent events, and optimization completions.

Webhook Events

  • performance.degradation
  • performance.improvement
  • agent.enabled
  • agent.disabled
  • optimization.complete
  • monitoring.alert
  • test.completed
  • subscription.updated

Webhook Payload Example

{
  "event": "performance.degradation",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "url": "https://example.com",
    "previousScore": 92,
    "currentScore": 78,
    "change": -14,
    "causes": [
      "Increased page size",
      "Slow server response time"
    ]
  },
  "webhook": {
    "id": "wh_123456",
    "attempt": 1
  }
}

Webhook Security

All webhooks are signed with HMAC-SHA256. Verify the signature using the X-SpeedThings-Signature header.

X-SpeedThings-Signature: sha256=abc123...

Error Handling

SpeedThings API uses conventional HTTP response codes and returns detailed error information in JSON format.

200 OK

Request succeeded

400 Bad Request

Invalid request parameters or missing required fields

401 Unauthorized

Authentication required or invalid credentials

403 Forbidden

Feature requires higher subscription plan

429 Too Many Requests

Rate limit exceeded

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_AGENT_ID",
    "message": "The specified agent ID does not exist",
    "details": {
      "agentId": "invalid-agent",
      "availableAgents": ["zapier-integration", "database-optimizer"]
    }
  },
  "request_id": "req_abc123"
}

SDKs & Libraries

Official SDKs and community libraries for popular programming languages and frameworks.

JavaScript / Node.js

npm install @speedthings/api
View Documentation →

Python

pip install speedthings-api
View Documentation →

PHP

composer require speedthings/api
View Documentation →

Quick Start Example (Node.js)

const SpeedThings = require('@speedthings/api');

const st = new SpeedThings({
  apiKey: 'st_live_key_...'
});

// Enable an MCP agent
async function enableZapierAgent() {
  try {
    const result = await st.agents.enable('zapier-integration', {
      api_key: 'your-zapier-key',
      triggers: ['performance_degradation']
    });
    console.log('Agent enabled:', result);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

// Run a speed test
async function testWebsite() {
  const results = await st.performance.test({
    url: 'https://example.com',
    device: 'desktop'
  });
  console.log('Speed score:', results.score);
}

Need Help with Integration?

Our developer support team is ready to help you build amazing integrations with SpeedThings.

Contact Support View Documentation