ScaleLens AI
Scan

Developer API

Submit implementation requests and query their status programmatically. Stable URL:https://scalelens.ai/api/public/v1/implementations

Your API keys

Keys are shown once — store them in a secret manager.

Loading…

Reference

Authentication

All endpoints require a Bearer token in the Authorization header.

Authorization: Bearer sl_live_xxxxxxxxxxxxxxxxxxxxxxxx

POST /api/public/v1/implementations

Submit a new implementation request for one of your saved scans.

curl -X POST https://scalelens.ai/api/public/v1/implementations \
  -H "Authorization: Bearer sl_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "scanId": "00000000-0000-0000-0000-000000000000",
    "contactEmail": "you@example.com",
    "notes": "Apply only meta + JSON-LD",
    "platform": "wordpress"
  }'

Returns 201 with { id, stage, status, createdAt }.

GET /api/public/v1/implementations?id=…

Query an existing request's status by its UUID.

curl https://scalelens.ai/api/public/v1/implementations?id=REQUEST_ID \
  -H "Authorization: Bearer sl_live_xxx"
{
  "id": "…",
  "url": "https://example.com",
  "stage": "in_progress",
  "platform": "shopify",
  "deliveredAt": null,
  "history": [
    { "stage": "requested",   "at": "2026-06-02T10:00:00Z" },
    { "stage": "queued",      "at": "2026-06-02T10:05:00Z" },
    { "stage": "in_progress", "at": "2026-06-02T11:00:00Z" }
  ]
}

Stages: requested · queued · in_progress · delivered · failed · cancelled.

Webhooks — async status updates

Background workers (CMS apply jobs, OAuth refreshers, queue runners) can advance an implementation request or update a connector's verification state without blocking the user. Each implementation request and each saved connector ships with a per-rowwebhookTokenthat authenticates one row only — never the whole account.

POST /api/public/webhooks/implementation-status
X-Webhook-Token: <implementation.webhookToken>
Content-Type: application/json

{
  "requestId": "REQUEST_UUID",
  "stage": "in_progress",       // requested|queued|in_progress|delivered|failed|cancelled
  "note":  "Theme apply 60% complete",
  "error": "Optional — sent with stage=failed"
}
POST /api/public/webhooks/connector-status
X-Webhook-Token: <connector.webhookToken>
Content-Type: application/json

{
  "connectorId": "CONNECTOR_UUID",
  "status": "connected",        // pending|connected|failed|revoked
  "error":  "Optional — sent with status=failed",
  "verifiedAt": "2026-06-03T12:00:00Z"
}

Both endpoints are idempotent — re-posting the same state is a safe no-op. Status changes on implementation requests automatically fire the matching stage email.

Errors

  • 401 — missing / unknown / revoked key, or wrong webhook token
  • 403 — scan does not belong to this key's owner
  • 404 — scan, request, or connector not found
  • 400 — invalid body (details in details)
Home