API Documentation

Quick Start

Get your API key from your account, then scan any URL in seconds.

curl -X POST https://cookieguardos.polsia.app/api/v1/scan \
  -H "Authorization: Bearer cg_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-site.com"}'

Authentication

All API requests require your API key as a Bearer token in the Authorization header.

Authorization: Bearer cg_your_api_key

If your key is invalid, you'll receive a 401 Unauthorized response. Sign up to get a key.

POST /api/v1/scan

Scans a URL for cookies and checks them against compliance rules (GDPR, ePrivacy). Returns within ~30 seconds.

Request Body

{
  "url": "https://example.com"
}

Response Format

{
  "success": true,
  "scan_id": "scan_1234567890_abc123",
  "url": "https://example.com",
  "domain": "example.com",
  "status": "fail",    // "pass" or "fail"
  "duration_ms": 813,
  "cookies": [
    {
      "name": "_ga",
      "domain": "example.com",
      "path": "/",
      "secure": true,
      "httpOnly": false,
      "sameSite": "lax",
      "maxAge": 63072000
    }
  ],
  "violations": [ /* see Violations section */ ],
  "summary": {
    "cookie_count": 4,
    "violation_count": 2,
    "critical": 1,
    "high": 1,
    "medium": 0,
    "low": 0
  }
}

Error Responses

Violations

Each violation in the violations array describes a compliance issue found.

{
  "rule": "no-tracking-before-consent",
  "severity": "critical",   // critical | high | medium | low
  "type": "consent",           // consent | security | retention
  "description": "Google Analytics cookie '_ga' set without consent...",
  "cookie": "_ga",
  "service": "Google Analytics",
  "category": "analytics"
}

Rules Checked

GitHub Action

Block PRs with cookie compliance violations automatically. Add one workflow file and every pull request gets scanned.

Setup

# Scans every PR for cookie compliance violations
name: Cookie Compliance

on:
  pull_request:
    branches: [main, master]

permissions:
  pull-requests: write

jobs:
  cookie-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Scan for cookie compliance
        uses: Polsia-Inc/cookieguardos/github-action@main
        with:
          url: 'https://your-site.com'
          api-key: ${{ secrets.COOKIEGUARD_API_KEY }}
          fail-on-violations: 'true'
          comment-on-pr: 'true'

GitHub Action Configuration

Outputs