Complete API Reference

All 60 endpoints across 15 sections

Authentication1 Users2 Consent Management3 Data Export3 Account Deletion4 Projects5 Sources10 Jobs5 Leads9 Email Verification3 Credits3 Markdown Exports7 Admin3 Webhooks1 Infrastructure1

Authentication

User authentication and session management

1 endpoint

POST/api/auth/signup

Public

Sign Up

Rate Limited: 5 requests per 15 minutes per IP address

Request Body

Name	Type	Required	Description
email	string	Required	User email address
password	string	Required	Password (minimum 8 characters)
name	string	Optional	User display name
termsAccepted	boolean	Required	Must be true to accept terms
privacyAccepted	boolean	Required	Must be true to accept privacy policy
marketingConsent	boolean	Optional	Opt-in to marketing emails

Example Request

curl -X POST "https://api.scrappy.gg/api/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password",
    "termsAccepted": true,
    "privacyAccepted": true
  }'

Responses

201User created successfully

{
  "success": true,
  "data": {
    "user": {
      "id": "abc123",
      "email": "user@example.com"
    }
  }
}

400Invalid input

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format"
  }
}

429Rate limit exceeded

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many attempts"
  }
}

Users

User profile and account management

2 endpoints

GET/api/users

Auth Required

Get Current User

Get the authenticated user's profile and statistics

Example Request

curl -X GET "https://api.scrappy.gg/api/users" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200User profile returned

{
  "success": true,
  "data": {
    "user": {
      "id": "abc123",
      "email": "user@example.com",
      "name": "John Doe",
      "createdAt": "2024-01-01T00:00:00Z"
    },
    "stats": {
      "sources": 10,
      "jobs": 25,
      "leads": 500
    }
  }
}

401Not authenticated

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

PATCH/api/users/password

Auth Required

Change Password

Update the authenticated user's password

Request Body

Name	Type	Required	Description
currentPassword	string	Required	Current password for verification
newPassword	string	Required	New password (minimum 8 characters)

Example Request

curl -X PATCH "https://api.scrappy.gg/api/users/password" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currentPassword": "your-password",
    "newPassword": "your-password"
  }'

Responses

200Password updated

{
  "success": true
}

400Invalid password

{
  "success": false,
  "error": {
    "code": "INVALID_PASSWORD",
    "message": "Current password is incorrect"
  }
}

Consent Management

GDPR consent preferences and history

3 endpoints

PATCH/api/users/consent

Auth Required

Update Consent

Update consent preferences (currently supports marketing consent)

Request Body

Name	Type	Required	Description
marketingConsent	boolean	Required	Whether to receive marketing emails

Example Request

curl -X PATCH "https://api.scrappy.gg/api/users/consent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "marketingConsent": true
  }'

Responses

200Consent updated

{
  "success": true,
  "data": {
    "marketingConsent": true,
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

GET/api/users/consent/history

Auth Required

Get Consent History

Get audit trail of consent changes

Query Parameters

Name	Type	Required	Description
limit	number	Optional	Number of records to returnDefault: 50
offset	number	Optional	Number of records to skipDefault: 0

Example Request

curl -X GET "https://api.scrappy.gg/api/users/consent/history" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Consent history returned

{
  "success": true,
  "data": {
    "history": [
      {
        "id": "abc123",
        "action": "CONSENT_UPDATED",
        "details": {
          "marketingConsent": true
        },
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "total": 1,
      "limit": 50,
      "offset": 0
    }
  }
}

Data Export

GDPR subject access requests - export your data

3 endpoints

POST/api/users/export

Auth Required

Request Data Export

Request an export of all your data (JSON or CSV format)

Rate Limited: 3 requests per 1 week per user

Request Body

Name	Type	Required	Description
format	string	Optional	Export formatOptions: JSON, CSVDefault: JSON

Example Request

curl -X POST "https://api.scrappy.gg/api/users/export" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Responses

200Export request created

{
  "success": true,
  "data": {
    "requestId": "abc123",
    "status": "PENDING",
    "downloadExpiry": "2024-01-08T00:00:00Z"
  }
}

429Rate limit exceeded

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Maximum 3 exports per week"
  }
}

GET/api/users/export/status

Auth Required

Get Export Status

Check the status of all export requests

Example Request

curl -X GET "https://api.scrappy.gg/api/users/export/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Export status returned

{
  "success": true,
  "data": {
    "exports": [
      {
        "requestId": "abc123",
        "status": "COMPLETED",
        "format": "JSON",
        "createdAt": "2024-01-01T00:00:00Z",
        "downloadExpiry": "2024-01-08T00:00:00Z"
      }
    ]
  }
}

GET/api/users/export/download

Auth Required

Download Export

Download a completed data export (7-day download window)

Query Parameters

Name	Type	Required	Description
requestId	string	Required	The export request ID

Example Request

curl -X GET ?requestId=abc123"https://api.scrappy.gg/api/users/export/download" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200File download

{
  "note": "Returns file attachment"
}

404Export not found or expired

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Export not found or expired"
  }
}

Account Deletion

GDPR right to erasure - delete your account

4 endpoints

POST/api/users/deletion

Auth Required

Request Account Deletion

Request deletion of your account. A confirmation email will be sent.

Rate Limited: 1 requests per 1 day per user

Example Request

curl -X POST "https://api.scrappy.gg/api/users/deletion" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Deletion requested

{
  "success": true,
  "data": {
    "expiresAt": "2024-01-02T00:00:00Z"
  }
}

429Rate limit exceeded

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "One deletion request per day"
  }
}

POST/api/users/deletion/confirm

Auth Required

Confirm Account Deletion

Confirm account deletion using the token from email. Starts 30-day grace period.

Request Body

Name	Type	Required	Description
token	string	Required	Confirmation token from email (24-hour expiry)

Example Request

curl -X POST "https://api.scrappy.gg/api/users/deletion/confirm" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "string"
  }'

Responses

200Deletion confirmed

{
  "success": true,
  "data": {
    "scheduledAt": "2024-01-31T00:00:00Z",
    "gracePeriodDays": 30
  }
}

400Invalid or expired token

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Token is invalid or expired"
  }
}

POST/api/users/deletion/cancel

Auth Required

Cancel Account Deletion

Cancel a pending account deletion during the grace period

Example Request

curl -X POST "https://api.scrappy.gg/api/users/deletion/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Deletion cancelled

{
  "success": true,
  "message": "Account deletion cancelled"
}

400No pending deletion

{
  "success": false,
  "error": {
    "code": "NO_PENDING_DELETION",
    "message": "No deletion request to cancel"
  }
}

GET/api/users/deletion/status

Auth Required

Get Deletion Status

Check the status of any pending account deletion

Example Request

curl -X GET "https://api.scrappy.gg/api/users/deletion/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Deletion status returned

{
  "success": true,
  "data": {
    "status": "scheduled",
    "scheduledAt": "2024-01-31T00:00:00Z",
    "gracePeriodDays": 30
  }
}

Projects

Organize sources and leads into projects

5 endpoints

GET/api/projects

Auth Required

List Projects

Get all projects for the authenticated user

Example Request

curl -X GET "https://api.scrappy.gg/api/projects" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Projects returned

{
  "success": true,
  "data": {
    "projects": [
      {
        "id": "abc123",
        "name": "My Project",
        "description": "Project description",
        "color": "#3b82f6",
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

POST/api/projects

Auth Required

Create Project

Create a new project

Request Body

Name	Type	Required	Description
name	string	Required	Project name
description	string	Optional	Project description
color	string	Optional	Hex color code (e.g., #3b82f6)

Example Request

curl -X POST "https://api.scrappy.gg/api/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Name"
  }'

Responses

201Project created

{
  "success": true,
  "data": {
    "project": {
      "id": "abc123",
      "name": "My Project"
    }
  }
}

GET/api/projects/[id]

Auth Required

Get Project

Get a specific project by ID

Path Parameters

Name	Type	Required	Description
id	string	Required	Project ID

Example Request

curl -X GET "https://api.scrappy.gg/api/projects/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Project returned

{
  "success": true,
  "data": {
    "project": {
      "id": "abc123",
      "name": "My Project"
    }
  }
}

404Project not found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Project not found"
  }
}

PATCH/api/projects/[id]

Auth Required

Update Project

Update a project's details

Path Parameters

Name	Type	Required	Description
id	string	Required	Project ID

Request Body

Name	Type	Required	Description
name	string	Optional	Project name
description	string	Optional	Project description
color	string	Optional	Hex color code

Example Request

curl -X PATCH "https://api.scrappy.gg/api/projects/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Responses

200Project updated

{
  "success": true,
  "data": {
    "project": {
      "id": "abc123",
      "name": "Updated Project"
    }
  }
}

403Not authorized

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Not authorized to update this project"
  }
}

DELETE/api/projects/[id]

Auth Required

Delete Project

Delete a project and all associated data

Path Parameters

Name	Type	Required	Description
id	string	Required	Project ID

Example Request

curl -X DELETE "https://api.scrappy.gg/api/projects/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Project deleted

{
  "success": true
}

403Not authorized

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Not authorized to delete this project"
  }
}

Sources

Manage data sources for lead scraping

10 endpoints

GET/api/sources

Auth Required

List Sources

Get all sources with optional filtering

Query Parameters

Name	Type	Required	Description
status	string	Optional	Filter by statusOptions: DRAFT, ACTIVE, ARCHIVED
projectId	string	Optional	Filter by project ID

Example Request

curl -X GET "https://api.scrappy.gg/api/sources" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Sources returned

{
  "success": true,
  "data": {
    "sources": [
      {
        "id": "abc123",
        "name": "Example Source",
        "url": "https://example.com",
        "scrapeType": "STATIC",
        "status": "ACTIVE"
      }
    ]
  }
}

POST/api/sources

Auth Required

Create Source

Create a new source for lead scraping

Request Body

Name	Type	Required	Description
name	string	Required	Source name
url	string	Required	URL to scrape
scrapeType	string	Required	Type of scrapingOptions: STATIC, DYNAMIC, API
selectors	object	Required	CSS/XPath selectors for data extraction
description	string	Optional	Source description
scheduleType	string	Optional	Scraping scheduleOptions: MANUAL, HOURLY, DAILY, WEEKLY

Example Request

curl -X POST "https://api.scrappy.gg/api/sources" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Name",
    "url": "https://example.com",
    "scrapeType": "string",
    "selectors": {}
  }'

Responses

201Source created

{
  "success": true,
  "data": {
    "source": {
      "id": "abc123",
      "name": "Example Source",
      "status": "DRAFT"
    }
  }
}

GET/api/sources/[id]

Auth Required

Get Source

Get a specific source by ID

Path Parameters

Name	Type	Required	Description
id	string	Required	Source ID

Example Request

curl -X GET "https://api.scrappy.gg/api/sources/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Source returned

{
  "success": true,
  "data": {
    "source": {
      "id": "abc123",
      "name": "Example Source"
    }
  }
}

PATCH/api/sources/[id]

Auth Required

Update Source

Update a source's configuration

Path Parameters

Name	Type	Required	Description
id	string	Required	Source ID

Request Body

Name	Type	Required	Description
name	string	Optional	Source name
url	string	Optional	URL to scrape
selectors	object	Optional	CSS/XPath selectors

Example Request

curl -X PATCH "https://api.scrappy.gg/api/sources/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Responses

200Source updated

{
  "success": true,
  "data": {
    "source": {
      "id": "abc123",
      "name": "Updated Source"
    }
  }
}

DELETE/api/sources/[id]

Auth Required

Delete Source

Delete a source

Path Parameters

Name	Type	Required	Description
id	string	Required	Source ID

Example Request

curl -X DELETE "https://api.scrappy.gg/api/sources/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Source deleted

{
  "success": true
}

POST/api/sources/[id]/activate

Auth Required

Activate Source

Activate a draft source to enable scraping

Path Parameters

Name	Type	Required	Description
id	string	Required	Source ID

Example Request

curl -X POST "https://api.scrappy.gg/api/sources/abc123/activate" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Source activated

{
  "success": true,
  "data": {
    "source": {
      "id": "abc123",
      "status": "ACTIVE"
    }
  }
}

400Already active

{
  "success": false,
  "error": {
    "code": "ALREADY_ACTIVE",
    "message": "Source is already active"
  }
}

POST/api/sources/discover

Auth Required

Discover Sources (AI)

Use AI to discover relevant sources based on a search query

Request Body

Name	Type	Required	Description
query	string	Required	Search query (minimum 3 characters)
count	number	Optional	Number of sources to discover (1-10)Default: 5

Example Request

curl -X POST "https://api.scrappy.gg/api/sources/discover" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "search term"
  }'

Responses

200Sources discovered

{
  "success": true,
  "data": {
    "sources": [
      {
        "name": "Example Directory",
        "url": "https://example.com/directory",
        "category": "Business Directory",
        "estimatedLeads": 500,
        "scrapeType": "STATIC",
        "description": "A directory of local businesses",
        "reasoning": "This directory contains relevant business listings"
      }
    ]
  }
}

POST/api/sources/generate

Auth Required

Generate Sources (AI)

Use AI to generate source suggestions based on a project description

Request Body

Name	Type	Required	Description
projectDescription	string	Required	Project description (minimum 10 characters)
targetAudience	string	Optional	Target audience for the leads
industry	string	Optional	Industry to focus on
location	string	Optional	Geographic location
count	number	Optional	Number of sources to generate (1-5)Default: 3
autoSave	boolean	Optional	Automatically save generated sources to the projectDefault: false

Example Request

curl -X POST "https://api.scrappy.gg/api/sources/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectDescription": "string"
  }'

Responses

200Sources generated

{
  "success": true,
  "data": {
    "sources": [
      {
        "name": "Industry Directory",
        "url": "https://example.com/directory",
        "description": "Relevant directory for target industry",
        "scrapeType": "STATIC",
        "reasoning": "Matches project requirements"
      }
    ]
  }
}

400Invalid input

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Project description must be at least 10 characters"
  }
}

POST/api/sources/batch

Auth Required

Batch Create Sources

Create multiple sources at once from AI suggestions or manual input

Request Body

Name	Type	Required	Description
sources	array	Required	Array of source objects to create (1 or more)
sources[].name	string	Required	Source name
sources[].url	string	Required	URL to scrape
sources[].description	string	Optional	Source description
sources[].scrapeType	string	Optional	Type of scrapingOptions: STATIC, DYNAMIC, APIDefault: DYNAMIC
sources[].selectors	object	Optional	CSS/XPath selectors for data extraction
sources[].reasoning	string	Optional	AI reasoning for why this source was suggested

Example Request

curl -X POST "https://api.scrappy.gg/api/sources/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [],
    "sources[].name": "Example Name",
    "sources[].url": "https://example.com"
  }'

Responses

201Sources created

{
  "success": true,
  "data": {
    "sources": [
      {
        "id": "abc123",
        "name": "Example Source",
        "status": "DRAFT"
      }
    ],
    "count": 1
  }
}

400Invalid input

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "At least one source is required"
  }
}

POST/api/sources/analyze

Auth Required

Analyze Source

Analyze project requirements from a URL or PDF file

Request Body

Name	Type	Required	Description
file	file	Optional	PDF file to analyze (mutually exclusive with url)
url	string	Optional	URL to analyze (mutually exclusive with file)

Example Request

curl -X POST "https://api.scrappy.gg/api/sources/analyze" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data"

Responses

200Analysis results

{
  "success": true,
  "data": {
    "requirements": {
      "targetAudience": "Small businesses",
      "industry": "Technology",
      "location": "United States",
      "suggestedSources": []
    }
  }
}

400Invalid input

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Either file or url is required"
  }
}

Jobs

Scraping job management and monitoring

5 endpoints

GET/api/jobs

Auth Required

List Jobs

Get all scraping jobs

Example Request

curl -X GET "https://api.scrappy.gg/api/jobs" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Jobs returned

{
  "success": true,
  "data": {
    "jobs": [
      {
        "id": "abc123",
        "name": "Scrape Job",
        "status": "COMPLETED",
        "progress": 100,
        "leadsFound": 150,
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

POST/api/jobs

Auth Required

Create Job

Create and enqueue a new scraping job

Request Body

Name	Type	Required	Description
name	string	Required	Job name
sourceId	string	Required	Source ID to scrape

Example Request

curl -X POST "https://api.scrappy.gg/api/jobs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Name",
    "sourceId": "abc123"
  }'

Responses

201Job created

{
  "success": true,
  "data": {
    "job": {
      "id": "abc123",
      "name": "Scrape Job",
      "status": "PENDING"
    }
  }
}

GET/api/jobs/[id]

Auth Required

Get Job

Get job details and progress

Path Parameters

Name	Type	Required	Description
id	string	Required	Job ID

Example Request

curl -X GET "https://api.scrappy.gg/api/jobs/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Job returned

{
  "success": true,
  "data": {
    "job": {
      "id": "abc123",
      "status": "RUNNING",
      "progress": 45,
      "leadsFound": 67
    }
  }
}

DELETE/api/jobs/[id]

Auth Required

Cancel/Delete Job

Cancel a running job or delete a completed job

Path Parameters

Name	Type	Required	Description
id	string	Required	Job ID

Example Request

curl -X DELETE "https://api.scrappy.gg/api/jobs/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Job cancelled/deleted

{
  "success": true
}

POST/api/jobs/[id]/retry

Auth Required

Retry Job

Retry a failed job

Path Parameters

Name	Type	Required	Description
id	string	Required	Job ID

Example Request

curl -X POST "https://api.scrappy.gg/api/jobs/abc123/retry" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Job retry started

{
  "success": true,
  "message": "Job retry started"
}

400Job cannot be retried

{
  "success": false,
  "error": {
    "code": "INVALID_STATUS",
    "message": "Only failed jobs can be retried"
  }
}

Leads

Lead management and email validation

9 endpoints

GET/api/leads

Auth Required

List Leads

Get all leads with optional filtering

Query Parameters

Name	Type	Required	Description
status	string	Optional	Filter by status
company	string	Optional	Filter by company name
jobId	string	Optional	Filter by job ID

Example Request

curl -X GET "https://api.scrappy.gg/api/leads" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Leads returned

{
  "success": true,
  "data": {
    "leads": [
      {
        "id": "abc123",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com",
        "company": "Example Inc",
        "status": "VALID"
      }
    ]
  }
}

POST/api/leads

Auth Required

Create Lead

Create a lead manually

Request Body

Name	Type	Required	Description
sourceUrl	string	Required	Source URL where lead was found
firstName	string	Optional	First name
lastName	string	Optional	Last name
email	string	Optional	Email address
phone	string	Optional	Phone number
company	string	Optional	Company name
jobTitle	string	Optional	Job title

Example Request

curl -X POST "https://api.scrappy.gg/api/leads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "https://example.com"
  }'

Responses

201Lead created

{
  "success": true,
  "data": {
    "lead": {
      "id": "abc123",
      "firstName": "John",
      "lastName": "Doe"
    }
  }
}

GET/api/leads/[id]

Auth Required

Get Lead

Get lead details with job and source info

Path Parameters

Name	Type	Required	Description
id	string	Required	Lead ID

Example Request

curl -X GET "https://api.scrappy.gg/api/leads/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Lead returned

{
  "success": true,
  "data": {
    "lead": {
      "id": "abc123",
      "email": "john@example.com"
    }
  }
}

PATCH/api/leads/[id]

Auth Required

Update Lead

Update a lead's information

Path Parameters

Name	Type	Required	Description
id	string	Required	Lead ID

Request Body

Name	Type	Required	Description
firstName	string	Optional	First name
lastName	string	Optional	Last name
email	string	Optional	Email address
status	string	Optional	Lead status
tags	array	Optional	Tags for categorization
notes	string	Optional	Notes about the lead

Example Request

curl -X PATCH "https://api.scrappy.gg/api/leads/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Responses

200Lead updated

{
  "success": true,
  "data": {
    "lead": {
      "id": "abc123"
    }
  }
}

DELETE/api/leads/[id]

Auth Required

Delete Lead

Delete a lead

Path Parameters

Name	Type	Required	Description
id	string	Required	Lead ID

Example Request

curl -X DELETE "https://api.scrappy.gg/api/leads/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Lead deleted

{
  "success": true
}

POST/api/leads/[id]/validate-email

Auth Required

Validate Lead Email

Trigger email validation for a specific lead

Path Parameters

Name	Type	Required	Description
id	string	Required	Lead ID

Example Request

curl -X POST "https://api.scrappy.gg/api/leads/abc123/validate-email" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Validation result

{
  "success": true,
  "data": {
    "status": "VALID",
    "tier": "TIER_1",
    "errors": [],
    "flags": []
  }
}

400No email on lead

{
  "success": false,
  "error": {
    "code": "NO_EMAIL",
    "message": "Lead has no email to validate"
  }
}

POST/api/leads/bulk

Auth Required

Bulk Delete Leads

Delete multiple leads at once (max 1000)

Request Body

Name	Type	Required	Description
leadIds	array	Required	Array of lead IDs to delete (1-1000)

Example Request

curl -X POST "https://api.scrappy.gg/api/leads/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leadIds": []
  }'

Responses

200Bulk delete result

{
  "success": true,
  "data": {
    "deleted": 50,
    "failed": 0,
    "errors": []
  }
}

PATCH/api/leads/bulk

Auth Required

Bulk Update Leads

Update multiple leads at once

Request Body

Name	Type	Required	Description
leadIds	array	Required	Array of lead IDs to update
updates	object	Required	Updates to apply (status, tags add/remove)

Example Request

curl -X PATCH "https://api.scrappy.gg/api/leads/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leadIds": [],
    "updates": {}
  }'

Responses

200Bulk update result

{
  "success": true,
  "data": {
    "updated": 50,
    "failed": 0
  }
}

POST/api/leads/validate-bulk

Auth Required

Bulk Validate Emails

Queue email validation for multiple leads (max 1000)

Request Body

Name	Type	Required	Description
leadIds	array	Required	Array of lead IDs to validate (1-1000)

Example Request

curl -X POST "https://api.scrappy.gg/api/leads/validate-bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leadIds": []
  }'

Responses

200Validation queued

{
  "success": true,
  "data": {
    "totalRequested": 100,
    "totalQueued": 95,
    "skipped": [
      {
        "id": "abc",
        "reason": "No email"
      }
    ]
  }
}

Email Verification

Email bounce tracking and spam trap detection

3 endpoints

POST/api/email-verification/bounce

Auth Required

Record Bounce

Record an email bounce event

Request Body

Name	Type	Required	Description
email	string	Required	Email address that bounced
bounceType	string	Required	Type of bounceOptions: HARD, SOFT, SPAM
bounceReason	string	Optional	Detailed bounce reason
smtpCode	string	Optional	SMTP error code

Example Request

curl -X POST "https://api.scrappy.gg/api/email-verification/bounce" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "bounceType": "string"
  }'

Responses

200Bounce recorded

{
  "success": true
}

POST/api/email-verification/spam-trap

Auth Required

Mark as Spam Trap

Mark an email as a known spam trap

Request Body

Name	Type	Required	Description
email	string	Required	Email address
confidence	number	Optional	Confidence level 0-100Default: 100
trapType	string	Optional	Type of spam trap
source	string	Optional	Source of identification

Example Request

curl -X POST "https://api.scrappy.gg/api/email-verification/spam-trap" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

Responses

200Spam trap marked

{
  "success": true
}

GET/api/email-verification/stats

Auth Required

Get Verification Stats

Get email verification and bounce statistics

Query Parameters

Name	Type	Required	Description
bounces	boolean	Optional	Include recent bounces
bounceLimit	number	Optional	Number of recent bouncesDefault: 100

Example Request

curl -X GET "https://api.scrappy.gg/api/email-verification/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Stats returned

{
  "success": true,
  "data": {
    "verificationStats": {
      "total": 1000,
      "valid": 850,
      "invalid": 100,
      "unknown": 50
    },
    "bounceStats": {
      "hard": 50,
      "soft": 30,
      "spam": 20
    },
    "recentBounces": []
  }
}

Credits

Credit balance and purchasing

3 endpoints

GET/api/credits/balance

Auth Required

Get Credit Balance

Get the current user's credit balance

Example Request

curl -X GET "https://api.scrappy.gg/api/credits/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Balance returned

{
  "success": true,
  "data": {
    "balance": 500,
    "configured": true,
    "costs": {
      "scrape": 1,
      "emailValidation": 0.5,
      "aiDiscovery": 5
    }
  }
}

GET/api/credits/pricing

Auth Required

Get Pricing Tiers

Get available credit pricing tiers for purchase

Example Request

curl -X GET "https://api.scrappy.gg/api/credits/pricing" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Pricing returned

{
  "success": true,
  "data": {
    "tiers": [
      {
        "id": "starter",
        "credits": 100,
        "price": 9.99
      },
      {
        "id": "pro",
        "credits": 500,
        "price": 39.99
      }
    ],
    "configured": true
  }
}

POST/api/credits/checkout

Auth Required

Create Checkout Session

Create a checkout session to purchase credits

Request Body

Name	Type	Required	Description
pricingTierId	string	Required	ID of the pricing tier to purchase

Example Request

curl -X POST "https://api.scrappy.gg/api/credits/checkout" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pricingTierId": "abc123"
  }'

Responses

200Checkout created

{
  "success": true,
  "data": {
    "url": "https://checkout.stripe.com/..."
  }
}

503Credits not configured

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Credits system not configured"
  }
}

Markdown Exports

Export websites to markdown format

7 endpoints

GET/api/markdown-exports

Auth Required

List Exports

Get all markdown exports

Example Request

curl -X GET "https://api.scrappy.gg/api/markdown-exports" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Exports returned

{
  "success": true,
  "data": {
    "exports": [
      {
        "id": "abc123",
        "name": "Example Site",
        "url": "https://example.com",
        "status": "COMPLETED",
        "pageCount": 25
      }
    ]
  }
}

POST/api/markdown-exports

Auth Required

Create Export

Create a new markdown export job

Request Body

Name	Type	Required	Description
name	string	Required	Export name
url	string	Required	URL to export
exportType	string	Optional	Export typeOptions: SINGLE_PAGE, FULL_SITEDefault: SINGLE_PAGE
maxPages	number	Optional	Maximum pages to export (1-1000)Default: 100
followExternal	boolean	Optional	Follow external links
useSitemap	boolean	Optional	Use sitemap.xml for discovery

Example Request

curl -X POST "https://api.scrappy.gg/api/markdown-exports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Name",
    "url": "https://example.com"
  }'

Responses

201Export created

{
  "success": true,
  "data": {
    "export": {
      "id": "abc123",
      "status": "PENDING"
    }
  }
}

GET/api/markdown-exports/[id]

Auth Required

Get Export

Get export details

Path Parameters

Name	Type	Required	Description
id	string	Required	Export ID

Example Request

curl -X GET "https://api.scrappy.gg/api/markdown-exports/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Export returned

{
  "success": true,
  "data": {
    "export": {
      "id": "abc123",
      "status": "COMPLETED"
    }
  }
}

DELETE/api/markdown-exports/[id]

Auth Required

Delete Export

Delete an export

Path Parameters

Name	Type	Required	Description
id	string	Required	Export ID

Example Request

curl -X DELETE "https://api.scrappy.gg/api/markdown-exports/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Export deleted

{
  "success": true
}

GET/api/markdown-exports/[id]/pages

Auth Required

Get Export Pages

Get all pages from an export with their markdown content

Path Parameters

Name	Type	Required	Description
id	string	Required	Export ID

Example Request

curl -X GET "https://api.scrappy.gg/api/markdown-exports/abc123/pages" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Pages returned

{
  "success": true,
  "data": {
    "pages": [
      {
        "id": "page123",
        "url": "https://example.com/page",
        "title": "Page Title",
        "markdown": "# Page Content..."
      }
    ]
  }
}

GET/api/markdown-exports/[id]/download

Auth Required

Download Export

Download export as ZIP or single markdown file

Path Parameters

Name	Type	Required	Description
id	string	Required	Export ID

Query Parameters

Name	Type	Required	Description
format	string	Optional	Download formatOptions: zip, singleDefault: zip

Example Request

curl -X GET "https://api.scrappy.gg/api/markdown-exports/abc123/download" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200File download

{
  "note": "Returns file attachment"
}

404No content

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Export has no content"
  }
}

POST/api/markdown-exports/[id]/retry

Auth Required

Retry Export

Retry a failed export

Path Parameters

Name	Type	Required	Description
id	string	Required	Export ID

Example Request

curl -X POST "https://api.scrappy.gg/api/markdown-exports/abc123/retry" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Export retry started

{
  "success": true,
  "message": "Export retry started"
}

Admin

Admin-only endpoints for platform management

3 endpoints

GET/api/admin/users

Admin Only

List All Users

Get all users with their statistics (admin only)

Example Request

curl -X GET "https://api.scrappy.gg/api/admin/users" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Users returned

{
  "success": true,
  "data": {
    "users": [
      {
        "id": "abc123",
        "email": "user@example.com",
        "stats": {
          "projects": 5,
          "sources": 20,
          "leads": 500,
          "jobs": 50
        }
      }
    ],
    "summary": {
      "total": 100,
      "active": 85,
      "newThisWeek": 10
    }
  }
}

403Not admin

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Admin access required"
  }
}

GET/api/admin/metrics/summary

Admin Only

Get Metrics Summary

Get aggregated platform metrics (admin only). Note: Response does not use standard wrapper format.

Example Request

curl -X GET "https://api.scrappy.gg/api/admin/metrics/summary" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Metrics returned

{
  "database": {
    "users": 100,
    "projects": 500,
    "sources": 1000,
    "leads": 50000,
    "jobs": 2000
  },
  "queues": {
    "waiting": {
      "scraping": 5,
      "emailValidation": 10
    },
    "active": {
      "scraping": 2,
      "emailValidation": 5
    },
    "failed": {
      "scraping": 0,
      "emailValidation": 1
    }
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

GET/api/admin/metrics/prometheus

Admin Only

Prometheus Query

Proxy Prometheus queries (admin only)

Query Parameters

Name	Type	Required	Description
query	string	Required	Prometheus query string
type	string	Optional	Query typeOptions: instant, rangeDefault: instant
start	string	Optional	Start time for range queries (ISO 8601)
end	string	Optional	End time for range queries (ISO 8601)
step	string	Optional	Query resolution stepDefault: 15s

Example Request

curl -X GET ?query=search term"https://api.scrappy.gg/api/admin/metrics/prometheus" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

200Prometheus query results

{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {
          "__name__": "up"
        },
        "value": [
          1704067200,
          "1"
        ]
      }
    ]
  }
}

400Missing query

{
  "error": "Query parameter is required"
}

Webhooks

Webhook endpoints for external integrations

1 endpoint

POST/api/webhooks/cred

Public

Cred.diy Webhook

Receive webhook events from cred.diy credits system. Requires signature verification.

Request Body

Name	Type	Required	Description
x-cred-signature	header	Required	HMAC-SHA256 signature for verification
x-cred-event	header	Required	Event type

Example Request

curl -X POST "https://api.scrappy.gg/api/webhooks/cred" \
  -H "Content-Type: application/json" \
  -d '{
    "x-cred-signature": "",
    "x-cred-event": ""
  }'

Responses

200Webhook received

{
  "received": true
}

401Invalid signature

{
  "error": "Invalid signature"
}

Infrastructure

Health checks and monitoring endpoints

1 endpoint

GET/api/health

Public

Health Check

Check the health status of all services

Example Request

curl -X GET "https://api.scrappy.gg/api/health"

Responses

200Health status

{
  "status": "healthy",
  "services": {
    "database": {
      "status": "healthy",
      "latency": 5
    },
    "redis": {
      "status": "healthy",
      "latency": 2
    }
  }
}

Need help? Check out our User Guides or contact support.

Complete API Reference

Table of Contents

Authentication

Sign Up

Request Body

Example Request

Responses

Users

Get Current User

Example Request

Responses

Change Password

Request Body

Example Request

Responses

Consent Management

Get Consent Status

Example Request

Responses

Update Consent

Request Body

Example Request

Responses

Get Consent History

Query Parameters

Example Request

Responses

Data Export

Request Data Export

Request Body

Example Request

Responses

Get Export Status

Example Request

Responses

Download Export

Query Parameters

Example Request

Responses

Account Deletion

Request Account Deletion

Example Request

Responses

Confirm Account Deletion

Request Body

Example Request

Responses

Cancel Account Deletion

Example Request

Responses

Get Deletion Status

Example Request

Responses

Projects

List Projects

Example Request

Responses

Create Project

Request Body

Example Request

Responses

Get Project

Path Parameters

Example Request

Responses

Update Project

Path Parameters

Request Body

Example Request

Responses

Delete Project

Path Parameters

Example Request

Responses

Sources

List Sources

Query Parameters

Example Request

Responses

Create Source