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}/action-snapshots/generate \
  -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. Generate action plan with the provided siteCheckId

Option 2: Polling

1. Call this endpoint (no callback URL)
2. Poll /api/site-checks/{siteCheckId}/status every 10s until status === "completed"
3. Generate action plan with /api/sites/{siteId}/action-snapshots/generate

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#

Action Items#

POST /sites/{siteId}/action-snapshots/generate#

Generates a new action plan snapshot from the latest site analysis.

Returns a snapshot ID that you use to fetch action items.

Parameters#

Request Body#

{
  "dimensions": [
    "url_health",
    "seo_elements",
    "icons_images"
  ],
  "triggeredBy": "n8n_daily_monitor"
}

Responses#

200 Snapshot generated#

{
  "id": "df5b6a9d-5c1e-4420-ae99-c5781e031043",
  "siteId": "303fe31c-963c-45dd-a35d-49460e71b16b",
  "totalActions": 11,
  "criticalCount": 0,
  "highCount": 5,
  "mediumCount": 4,
  "lowCount": 2
}

401 Unauthorized - Missing or invalid API key#

{
  "error": "Unauthorized"
}

404 Resource not found#

GET /action-snapshots/{snapshotId}/actions#

Get action items from a snapshot with flexible views for automation.

Zero-Code Routing Decision Tree#

Use ?view=routing in n8n/Zapier for IF/THEN routing without JavaScript:

1. Check if {{ $json.routing_hints.has_critical }}
   → YES: Send urgent Slack alert + page engineer
   → NO: Continue

2. Check if {{ $json.routing_hints.has_auto_fixable_meta }}
   → YES: Trigger auto-fix workflow (generate meta tags)
   → NO: Continue

3. Check if {{ $json.routing_hints.has_auto_fixable_schema }}
   → YES: Trigger schema generation workflow
   → NO: Continue

4. Check if {{ $json.routing_hints.has_indexing_issues }}
   → YES: Submit URLs to GSC for indexing
   → NO: Continue

5. Check if {{ $json.routing_hints.has_any_actions }}
   → YES: Send summary email
   → NO: No action needed, send "All Good" notification

n8n Example - IF Node Configuration:

• Condition: {{ $json.routing_hints.has_critical }} equals true
• True branch: Slack webhook node
• False branch: Next decision node

View Types#

flat (default)#

Returns a flat array of all action items. Use for custom filtering.

routing - Recommended for n8n/Zapier#

Returns routing hints and counts for zero-code automation.

{
  "routing_hints": {
    "has_auto_fixable_meta": true,
    "has_critical": false,
    "recommended_next_action": "fix_meta_tags"
  },
  "counts": {
    "total_actions": 11,
    "auto_fixable": 8
  }
}

grouped#

Returns actions pre-organized by type for batch processing.

Use case: Iterate through groups.auto_fixable.actions to bulk-fix issues.

summary#

Returns statistics and top actions for dashboards.

Use case: Display health score and top 3 issues in Slack/email.

Filters#

Combine with view parameter:

• auto_fixable - Only auto-fixable actions
• manual_review - Only manual review actions
• critical, high, medium, low - By priority
• meta, schema, indexing, og_images - By type

Examples:

• ?view=routing - Get routing hints
• ?view=grouped - Get organized groups
• ?filter=auto_fixable&view=grouped - Get only auto-fixable, grouped
• ?filter=critical&view=flat - Get critical issues as array

Parameters#

Responses#

200 Success#

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