Snapshots & Diffing

Every extraction creates a snapshot. Compare snapshots to detect design changes over time.

Endpoints

List Snapshots

Get all snapshots for an extraction.

GET /api/extractions/:id/snapshots

Response:

{
  "data": [
    {
      "id": "snap_abc123",
      "extraction_id": "ext_abc123",
      "version": 3,
      "created_at": "2024-01-17T10:30:00Z"
    },
    {
      "id": "snap_xyz789",
      "extraction_id": "ext_abc123",
      "version": 2,
      "created_at": "2024-01-16T10:30:00Z"
    },
    {
      "id": "snap_def456",
      "extraction_id": "ext_abc123",
      "version": 1,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Compare Snapshots

Get a diff between two snapshots.

GET /api/extractions/:id/diff

Query Parameters:

Example:

curl "https://api.stylegrab.dev/api/extractions/ext_abc123/diff?from=snap_def456&to=snap_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "from": {
    "id": "snap_def456",
    "version": 1,
    "created_at": "2024-01-15T10:30:00Z"
  },
  "to": {
    "id": "snap_abc123",
    "version": 3,
    "created_at": "2024-01-17T10:30:00Z"
  },
  "changes": {
    "colors": {
      "added": [
        {"name": "accent", "value": "#10b981"}
      ],
      "removed": [
        {"name": "secondary", "value": "#6b7280"}
      ],
      "modified": [
        {
          "name": "primary",
          "from": "#3b82f6",
          "to": "#2563eb"
        }
      ]
    },
    "typography": {
      "added": [],
      "removed": [],
      "modified": [
        {
          "family": "Inter",
          "changes": {
            "weights": {
              "added": ["800"],
              "removed": []
            }
          }
        }
      ]
    },
    "spacing": {
      "added": ["40px", "56px"],
      "removed": ["36px"]
    }
  },
  "summary": {
    "total_changes": 7,
    "colors_changed": 3,
    "typography_changed": 1,
    "spacing_changed": 3
  }
}

Diff Structure

Added

Tokens that exist in to but not in from:

{
  "added": [
    {"name": "accent", "value": "#10b981"}
  ]
}

Removed

Tokens that exist in from but not in to:

{
  "removed": [
    {"name": "secondary", "value": "#6b7280"}
  ]
}

Modified

Tokens that exist in both but with different values:

{
  "modified": [
    {
      "name": "primary",
      "from": "#3b82f6",
      "to": "#2563eb"
    }
  ]
}

Use Cases

Scheduled Monitoring

Run extractions on a schedule to detect drift:

# Cron job: Extract daily at midnight
0 0 * * * curl -X POST https://api.stylegrab.dev/api/extractions \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"url": "https://yoursite.com"}'

Pre-Deploy Checks

Compare staging vs production before deploying:

# Extract from staging
STAGING=$(curl -X POST .../extractions -d '{"url": "https://staging.yoursite.com"}')
STAGING_SNAP=$(echo $STAGING | jq -r '.id')

# Compare with latest production snapshot
curl ".../extractions/$PROD_EXT_ID/diff?from=$PROD_SNAP&to=$STAGING_SNAP"

Design System Audits

Track when components drift from the design system:

1. Extract tokens from your design system documentation
2. Extract tokens from production
3. Compare to find inconsistencies

Webhooks

Get notified when diffs are detected:

{
  "event": "diff.detected",
  "url": "https://yoursite.com/webhooks/stylegrab"
}

See Webhooks for setup details.