REST API Reference

Complete REST API reference for programmatic access to Rampify's SEO intelligence.

Quick Start#

1. Generate API Key#

Get your API key from Settings → API Keys:

# Your key will look like this
sk_live_abc123def456...

2. Set Environment Variable#

export RAMPIFY_API_KEY=sk_live_abc123...

3. Make Your First Request#

curl https://www.rampify.dev/api/clients/{clientId}/analyze \
  -H "Authorization: Bearer $RAMPIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"callbackUrl": "https://hooks.n8n.cloud/webhook/abc123"}'

Authentication#

All endpoints require API key authentication. Include your API key in the Authorization header:

curl https://www.rampify.dev/api/sites/{siteId}/feature-specs \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json"

Get your API key: Settings → API Keys

Sites#

POST /clients/{clientId}/analyze#

Triggers a full site crawl and analysis. This is an asynchronous operation that returns immediately with a siteCheckId for polling.

Workflow Options:

Option 1: Webhook (Recommended for n8n/Zapier)

1. Call this endpoint with callbackUrl in request body
2. Continue with other tasks - no polling needed
3. Receive POST to your callback URL when complete
4. Fetch the generated specs with /api/sites/{siteId}/feature-specs

Option 2: Polling

1. Call this endpoint (no callback URL)
2. Poll /api/site-checks/{siteCheckId}/status every 10s until status === "completed"
3. Fetch the generated specs with /api/sites/{siteId}/feature-specs

Parameters#

Request Body#

Optional webhook configuration - Skip polling by providing a callbackUrl.

When analysis completes, Rampify POSTs to your webhook with:

• event: "analysis.completed"
• data.siteCheckId: Use to generate action plan
• data.status: "completed"
• data.totalUrls, data.urlsChecked, data.issuesFound

Perfect for n8n Wait nodes and Zapier webhooks.

{
  "callbackUrl": "https://hooks.n8n.cloud/webhook/abc123"
}

Responses#

200 Analysis started successfully#

{
  "success": true,
  "siteId": "303fe31c-963c-45dd-a35d-49460e71b16b",
  "siteCheckId": "0af7de47-8fff-4a89-83bc-002436ef2a8b",
  "backgroundJob": "in_progress",
  "summary": {
    "totalUrls": 28,
    "urlsChecked": 0,
    "issuesFound": 0,
    "criticalIssues": 0,
    "warnings": 0,
    "duration": 2907
  },
  "issues": [],
  "message": "Found 28 URLs. Checking URLs in background..."
}

401 Unauthorized - Missing or invalid API key#

{
  "error": "Unauthorized"
}

404 Resource not found#

GET /site-checks/{siteCheckId}/status#

Check the status of a background site analysis.

Poll every 10 seconds until status === "completed"

Parameters#

Responses#

200 Status retrieved#

{
  "urls_checked": 28,
  "total_urls": 28,
  "status": "completed"
}

401 Unauthorized - Missing or invalid API key#

{
  "error": "Unauthorized"
}

404 Resource not found#

Rate Limits#

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 943
X-RateLimit-Reset: 1634567890

Error Handling#

Errors follow this format:

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "details": {}
  }
}

Common error types:

• authentication_error - Invalid API key
• rate_limit_error - Too many requests
• validation_error - Invalid parameters
• not_found_error - Resource not found
• tier_required_error - Feature requires upgrade