API Reference

Complete reference for the DoppelDown brand protection API. All endpoints are served from https://doppeldown.com/api.

Base URL: https://doppeldown.com/apiAuth: Supabase Session / Bearer TokenFormat: JSON

Authentication

DoppelDown uses Supabase Auth for authentication. Browser-based requests use session cookies automatically. For programmatic access, include the access token as a Bearer token.

Authorization Header

Authorization: Bearer <supabase_access_token>

Cron endpoints use a separate shared secret: Authorization: Bearer <CRON_SECRET>

Common Auth Errors

Status	Code	Description
401	—	Missing or invalid session / token
403	—	Valid auth but insufficient permissions (e.g. not admin)

Brands

List Brands

GET/api/brands

Retrieve all brands owned by the authenticated user, ordered by creation date (newest first).

Response 200

[
  {
    "id": "uuid",
    "user_id": "uuid",
    "name": "Acme Corp",
    "domain": "acme.com",
    "keywords": ["acme", "acmecorp"],
    "social_handles": { "twitter": ["@acmecorp"] },
    "enabled_social_platforms": ["twitter", "instagram"],
    "logo_url": "https://...",
    "status": "active",
    "threat_count": 5,
    "created_at": "2025-01-15T00:00:00Z"
  }
]

curl

curl -X GET https://doppeldown.com/api/brands \
  -H "Authorization: Bearer $TOKEN"

Create Brand

POST/api/brands

Create a new brand to monitor. Domain is auto-normalized (strips protocol, www, paths).

Parameter	Type	Required	Description
name	string	Required	Brand display name
domain	string	Required	Primary domain (auto-normalized)
keywords	string[]	Optional	Additional keywords to monitor
social_handles	object	Optional	Map of platform → handle arrays
enabled_social_platforms	string[]	Optional	Platforms to scan (max depends on tier)

Status	Code	Description
400	—	Missing name or domain
403	BRAND_LIMIT_REACHED	Plan brand limit exceeded
403	PLATFORM_LIMIT_EXCEEDED	Too many social platforms for tier

curl

curl -X POST https://doppeldown.com/api/brands \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "domain": "https://www.acme.com",
    "keywords": ["acme", "acmecorp"],
    "social_handles": { "twitter": ["@acmecorp"] },
    "enabled_social_platforms": ["twitter", "instagram"]
  }'

Update Brand

PATCH/api/brands

Update an existing brand. Only provided fields are changed. Social handles can be merged or replaced.

Parameter	Type	Required	Description
brandId	string	Required	Brand UUID to update
name	string	Optional	New brand name
domain	string	Optional	New primary domain
keywords	string[]	Optional	Replacement keywords array
social_handles	object	Optional	Social handles (merged by default)
enabled_social_platforms	string[]	Optional	Updated enabled platforms
mode	string	Default: "merge"	"merge" or "replace" for social_handles

Status	Code	Description
400	—	Invalid input or no updates provided
403	PLATFORM_LIMIT_EXCEEDED	Too many platforms for tier
404	—	Brand not found or not owned by user

curl

curl -X PATCH https://doppeldown.com/api/brands \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "uuid-here",
    "keywords": ["acme", "acmecorp", "acme-inc"]
  }'

Upload Brand Logo

POST/api/brands/logo

Upload a PNG logo for a brand. Max file size: 5 MB.

Content-Type must be multipart/form-data. Only PNG images are accepted.

Parameter	Type	Required	Description
brandId	string	Required	Brand UUID (form field)
logo	File	Required	PNG image file (max 5MB)

Response 200

{
  "logo_url": "https://supabase-storage-url/...",
  "storage_path": "brands/{brandId}/logo/{timestamp}-{uuid}-{name}.png"
}

curl

curl -X POST https://doppeldown.com/api/brands/logo \
  -H "Authorization: Bearer $TOKEN" \
  -F "brandId=uuid-here" \
  -F "logo=@/path/to/logo.png"

Delete Brand Logo

DELETE/api/brands/logo

Remove a brand's logo from storage and clear the URL.

Parameter	Type	Required	Description
brandId	string	Required	Brand UUID

curl

curl -X DELETE https://doppeldown.com/api/brands/logo \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "brandId": "uuid-here" }'

Scans

Start Scan

POST/api/scan

Queue a new scan for a brand. Enforces manual scan quotas per tier (free: 3 per 7 days, paid: unlimited).

Parameter	Type	Required	Description
brandId	string	Required	Brand UUID to scan
scanType	string	Default: "full"	full \| quick \| domain_only \| web_only \| social_only

Response 200

{
  "message": "Scan queued",
  "scanId": "uuid",
  "jobId": "uuid"
}

Status	Code	Description
400	—	Missing brandId
404	—	Brand not found
409	—	Scan already queued or running for this brand
429	QUOTA_EXCEEDED	Manual scan quota exceeded (includes quota object)

curl

curl -X POST https://doppeldown.com/api/scan \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "brandId": "uuid-here", "scanType": "full" }'

Get Scan Status

GET/api/scan?id={scanId}

Retrieve details and progress for a specific scan.

Parameter	Type	Required	Description
id	string	Required	Scan UUID (query parameter)

Response 200

{
  "id": "uuid",
  "brand_id": "uuid",
  "scan_type": "full",
  "status": "running",
  "threats_found": 3,
  "domains_checked": 150,
  "pages_scanned": 42,
  "created_at": "2025-01-15T10:00:00Z",
  "completed_at": null,
  "error": null
}

curl

curl -X GET "https://doppeldown.com/api/scan?id=uuid-here" \
  -H "Authorization: Bearer $TOKEN"

Cancel Scan

POST/api/scan/cancel

Cancel a queued or running scan. Sets both the scan and its jobs to cancelled/failed status.

Parameter	Type	Required	Description
scanId	string	Required	Scan UUID to cancel

Response 200

{ "message": "Scan cancelled", "scanId": "uuid" }

curl

curl -X POST https://doppeldown.com/api/scan/cancel \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "scanId": "uuid-here" }'

Get Scan Quota

GET/api/scan/quota

Check the current user's manual scan quota. Free tier has a 7-day rolling window; paid tiers are unlimited.

Response 200 (Free tier)

{
  "limit": 3,
  "used": 1,
  "remaining": 2,
  "resetsAt": 1705363200000,
  "isUnlimited": false
}

Response 200 (Paid tier / Admin)

{
  "limit": null,
  "used": 0,
  "remaining": null,
  "resetsAt": null,
  "isUnlimited": true
}

curl

curl -X GET https://doppeldown.com/api/scan/quota \
  -H "Authorization: Bearer $TOKEN"

Start Social Scan

POST/api/scan/social

Queue a social-media-only scan targeting specific platforms.

Parameter	Type	Required	Description
brandId	string	Required	Brand UUID
platforms	string[]	Default: All 8 platforms	Platforms to scan

Response 200

{
  "success": true,
  "message": "Social scan queued",
  "scanId": "uuid",
  "jobId": "uuid",
  "platforms": ["twitter", "instagram", "tiktok"]
}

Status	Code	Description
409	—	Scan already queued or running for this brand

curl

curl -X POST https://doppeldown.com/api/scan/social \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "uuid-here",
    "platforms": ["twitter", "instagram", "tiktok"]
  }'

Delete Scan

DELETE/api/scans/{id}

Permanently delete a scan and cascade-delete all associated threats and evidence files.

This action is irreversible. All threats and evidence screenshots linked to this scan will be permanently deleted.

Response 200

{ "success": true }

curl

curl -X DELETE https://doppeldown.com/api/scans/uuid-here \
  -H "Authorization: Bearer $TOKEN"

Threats

Delete Threat

DELETE/api/threats/{id}

Permanently delete a threat and its evidence files. Creates an audit log entry.

Evidence screenshots are removed from storage on a best-effort basis.

Response 200

{ "success": true }

curl

curl -X DELETE https://doppeldown.com/api/threats/uuid-here \
  -H "Authorization: Bearer $TOKEN"

Evidence

Sign Evidence URL

POST/api/evidence/sign

GET/api/evidence/sign?threatId={id}&kind={kind}

Generate a time-limited signed URL for accessing evidence files (screenshots or HTML snapshots). Supports both GET and POST.

Parameter	Type	Required	Description
threatId	string	Required	Threat UUID
kind	string	Default: "screenshot"	"screenshot" or "html"
index	number	Default: 0	Index of the evidence item
expiresIn	number	Default: 3600	TTL in seconds (60–86400)

Response 200

{
  "signedUrl": "https://supabase-storage/...",
  "expiresIn": 3600,
  "bucket": "evidence",
  "path": "threats/{id}/screenshot-0.png"
}

curl (POST)

curl -X POST https://doppeldown.com/api/evidence/sign \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "threatId": "uuid-here", "kind": "screenshot", "expiresIn": 7200 }'

Reports

Generate Report

POST/api/reports

Generate a takedown report for threats associated with a brand. Returns a downloadable file.

Parameter	Type	Required	Description
brandId	string	Required	Brand UUID
threatIds	string[]	Default: All unresolved	Specific threat UUIDs to include
format	string	Default: "html"	html \| text \| csv \| json
ownerName	string	Default: User email	Name for "brand owner" field

Response is a file download, not JSON. The X-Report-Id header contains the report record UUID.

Format	Content-Type	Extension
html	text/html	.html
text	text/plain	.txt
csv	text/csv	.csv
json	application/json	.txt

curl

curl -X POST https://doppeldown.com/api/reports \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "uuid-here",
    "format": "html",
    "ownerName": "Acme Legal Team"
  }' \
  -o takedown-report.html

List Reports

GET/api/reports

List all generated reports, optionally filtered by brand.

Parameter	Type	Required	Description
brandId	string	Optional	Filter by brand UUID (query parameter)

Response 200

[
  {
    "id": "uuid",
    "brand_id": "uuid",
    "threat_ids": ["uuid-1", "uuid-2"],
    "type": "takedown_request",
    "status": "ready",
    "created_at": "2025-01-15T10:00:00Z",
    "brands": { "user_id": "uuid", "name": "Acme Corp" }
  }
]

curl

curl -X GET "https://doppeldown.com/api/reports?brandId=uuid-here" \
  -H "Authorization: Bearer $TOKEN"

Delete Report

DELETE/api/reports/{id}

Delete a report record. Creates an audit log entry.

Response 200

{ "success": true }

curl

curl -X DELETE https://doppeldown.com/api/reports/uuid-here \
  -H "Authorization: Bearer $TOKEN"

Notifications

Get Notifications

GET/api/notifications

Retrieve up to 50 notifications (newest first) plus the unread count.

Response 200

{
  "notifications": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "type": "threat_detected",
      "title": "New threat found",
      "message": "Suspicious domain acme-corp.xyz detected",
      "read": false,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "unread_count": 3
}

curl

curl -X GET https://doppeldown.com/api/notifications \
  -H "Authorization: Bearer $TOKEN"

Mark Notifications Read

PATCH/api/notifications

Mark specific notifications or all notifications as read.

Parameter	Type	Required	Description
ids	string[]	Optional	Specific notification UUIDs to mark read
mark_all_read	boolean	Optional	Set true to mark all as read

One of ids or mark_all_read must be provided.

curl (mark all)

curl -X PATCH https://doppeldown.com/api/notifications \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "mark_all_read": true }'

curl (specific IDs)

curl -X PATCH https://doppeldown.com/api/notifications \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["uuid-1", "uuid-2"] }'

Billing (Stripe)

Create Checkout Session

POST/api/stripe/checkout

Start a Stripe Checkout flow to subscribe to a plan. Returns a redirect URL.

Parameter	Type	Required	Description
plan	string	Required	"starter", "professional", or "enterprise"

Response 200

{ "url": "https://checkout.stripe.com/c/pay/..." }

Status	Code	Description
400	—	Invalid plan or Stripe price ID not configured

curl

curl -X POST https://doppeldown.com/api/stripe/checkout \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "plan": "professional" }'

Create Portal Session

POST/api/stripe/portal

Open the Stripe Customer Portal for managing subscriptions, invoices, and payment methods.

Response 200

{ "url": "https://billing.stripe.com/p/session/..." }

Status	Code	Description
400	—	No subscription found (user has no Stripe customer ID)

curl

curl -X POST https://doppeldown.com/api/stripe/portal \
  -H "Authorization: Bearer $TOKEN"

Stripe Webhook

POST/api/stripe/webhook

Receives Stripe webhook events. Configured in the Stripe Dashboard — not called directly by clients.

Authenticated via stripe-signature header, not Bearer tokens.

Event	Action
checkout.session.completed	Activates subscription, sets tier
customer.subscription.updated	Updates subscription status and tier
customer.subscription.deleted	Resets user to free tier
invoice.payment_failed	Sets subscription to past_due

Admin

Get Audit Logs

GET/api/admin/audit-logs

Retrieve system audit logs. Admin only — requires the is_admin flag on the user record.

Parameter	Type	Required	Description
entity_type	string	Optional	Filter by entity: scan, threat, report
user_id	string	Optional	Filter by user UUID
limit	number	Default: 100	Results per page (max 500)
offset	number	Default: 0	Pagination offset

Response 200

{
  "logs": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "user_email": "admin@example.com",
      "action": "DELETE",
      "entity_type": "threat",
      "entity_id": "uuid",
      "metadata": {
        "brand_id": "uuid",
        "threat_type": "typosquat_domain",
        "severity": "high"
      },
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 42,
  "limit": 100,
  "offset": 0
}

Status	Code	Description
403	—	User is not an admin

curl

curl -X GET "https://doppeldown.com/api/admin/audit-logs?entity_type=scan&limit=50" \
  -H "Authorization: Bearer $TOKEN"

Cron Jobs

These endpoints are called by an external scheduler (e.g. Vercel Cron) and require Authorization: Bearer <CRON_SECRET>.

Automated Scan Scheduler

GET/api/cron/scan

Queues automated scans for all active brands based on tier-specific scan frequency. Adds random jitter (0–5 min) to spread load.

Tier	Scan Frequency
Free	Skipped (manual only)
Starter	Every 24 hours
Professional	Every 6 hours
Enterprise	Every 1 hour

Response 200

{
  "success": true,
  "results": { "queued": 12, "skipped": 5, "errors": [] },
  "timestamp": "2025-01-15T10:00:00Z"
}

Weekly Digest

GET/api/cron/digest

Sends weekly email digests to users with email alerts enabled. Aggregates threats from the past 7 days per brand (max 10 per brand to avoid email clipping).

Response 200

{
  "success": true,
  "results": { "sent": 8, "skipped": 3, "errors": [] },
  "timestamp": "2025-01-15T10:00:00Z"
}

NRD Monitor

GET/api/cron/nrd

Processes newly registered domains against enterprise brands for typosquatting detection. Max execution time: 5 minutes. Enterprise tier only.

Response 200

{
  "success": true,
  "results": {
    "domainsProcessed": 50000,
    "matchesFound": 3,
    "threatsCreated": 1,
    "errors": []
  },
  "processingTimeMs": 45000,
  "timestamp": "2025-01-15T10:00:00Z"
}

Tier Limits Reference

Feature	Free	Starter	Professional	Enterprise
Brands	1	3	10	Unlimited
Domain variations / scan	25	100	500	2,500
Social platforms	1	3	6	8 (all)
Automated scan frequency	Manual only	Every 24h	Every 6h	Every 1h
Manual scans	3 / 7 days	Unlimited	Unlimited	Unlimited
NRD monitoring	✗	✗	✗	✓

Available social platforms: twitter, facebook, instagram, linkedin, tiktok, youtube, telegram, discord

Error Codes

All error responses follow this format:

{ "error": "Human-readable message", "code": "MACHINE_READABLE_CODE" }

Application Error Codes

Status	Code	Description
403	BRAND_LIMIT_REACHED	User has reached their plan's brand limit
403	PLATFORM_LIMIT_EXCEEDED	Too many social platforms selected for tier
429	QUOTA_EXCEEDED	Manual scan quota depleted for the current period

HTTP Status Codes

Status	Meaning
200	Success
400	Bad request / validation error
401	Not authenticated
403	Forbidden / tier limit reached
404	Resource not found
409	Conflict (e.g. duplicate scan)
429	Rate limited / quota exceeded
500	Internal server error

DoppelDown API Documentation — doppeldown.com