leadgenius-cli（leadgenius CLI 搜索）

LeadGenius Pro — CLI & Automation API Skill

This skill teaches AI agents how to operate the LeadGenius Pro Automation API and the lgp CLI tool. It covers the full lifecycle of B2B lead management — from ICP (Ideal Customer Profile) definition and automated lead generation through enrichment, scoring, qualification, and email delivery via the FSD (Full-Stack Demand) pipeline.

Base URL

https://api.leadgenius.app

All API endpoints live under /api/automation/.

Authentication

Every request must include an API key in the X-API-Key header:

X-API-Key: lgp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Keys are prefixed with lgp_ and tied to a specific company.
• The key determines company_id, owner identity, and rate limits.
• Keys are created via POST /api/automation/users/provision — the plain-text key is returned only once at creation time.
• Test your key with GET /api/automation/auth/test.

Rate Limits

Admin Key (Rate Limit Bypass)

An optional X-Admin-Key header can be sent alongside X-API-Key to bypass application-level rate limits:

X-API-Key: lgp_your_key_here
X-Admin-Key: your_admin_key_here

Behavior:

• When both X-API-Key and X-Admin-Key are present, the API key is validated normally (real company context is preserved) and rate limits are skipped.
• When only X-Admin-Key is present (no API key), the request runs as admin-master-company — only useful for admin-only endpoints like /api/admin/*.
• The admin key does not bypass AWS WAF rules. Rapid bursts of requests from the same IP will still be blocked at the infrastructure level regardless of the admin key.

Important for AI agents: Always include X-API-Key alongside X-Admin-Key. Using the admin key alone will cause company-scoped queries (leads, settings, tasks) to return empty results because they filter by admin-master-company.

AWS WAF Throttling

The API is protected by AWS WAF, which blocks IPs after too many requests in a short window. This is separate from the application rate limiter and cannot be bypassed by the admin key.

Best practices for AI agents:

• Add 3-5 second delays between consecutive API calls
• Use exponential backoff on connection failures (fetch failed errors)
• Batch operations where possible (e.g., leads import with a leads array instead of individual imports)
• If you get repeated connection failures, wait 60 seconds before retrying

Prerequisites Checklist

Before running enrichment, copyright, scoring, or FSD pipelines, the following configuration records must exist. Create them via the Tables API (POST /api/automation/tables/{tableName}).

Note on settings creation: The AgentSettings, SdrAiSettings, and UrlSettings tables do not accept company_id or owner in the create input — these are managed automatically. The Tables API handles this by stripping these fields during creation and setting company_id via a post-creation update. When creating settings via direct GraphQL, create the record first, then update it to set company_id.

UrlSettings (required for enrichment)

AgentSettings (required for copyright / AI content generation)

SdrAiSettings (required for SDR AI scoring)

ICP with Apify Config (required for lead generation)

Client (required for data isolation)

EmailPlatformSettings (required for email delivery)

Quick-Reference: Endpoint Map

Quick-Reference: CLI Map

The lgp CLI is the sole command-line tool for LeadGenius Pro. Run via npx tsx src/scripts/lgp.ts <command>.

Lead Lifecycle: Soft-Delete, Restore & Purge

The leads command group supports a soft-delete lifecycle for safe lead removal:

Soft-deleted leads are excluded from leads list by default. Use includeDeleted=true query parameter on the API to include them.

Lead Import Integrity

The leads import command supports enhanced duplicate detection and idempotency:

• strictMode: Rejects imports when duplicates are found (409 Conflict). For batch imports, rejects the entire batch.
• verificationLevels: Configure which identity fields (email, linkedinUrl, companyFullName) are used for duplicate detection.
• X-Idempotency-Key: Same key within 24 hours returns the cached response instead of re-importing.

Maintenance

Maintenance bugs and enhancements are managed through the lgp TypeScript CLI:

# List bugs
npx tsx src/scripts/lgp.ts maintenance bugs list

# Report a bug
npx tsx src/scripts/lgp.ts maintenance bugs report --desc "Login fails on mobile"

# List enhancements
npx tsx src/scripts/lgp.ts maintenance enhancements list

# Request an enhancement
npx tsx src/scripts/lgp.ts maintenance enhancements request --desc "Add bulk export feature"

See references/cli_reference.md#maintenance for full documentation.

Note: Legacy standalone Node.js scripts (scripts/create-maintenance-item.js, scripts/list-maintenance-items.js, scripts/update-maintenance-item.js) still exist but the lgp CLI is the recommended interface.

E2E Pipeline Testing

A comprehensive E2E test script validates the full autonomous lead lifecycle across 15 pipeline phases:

# Run the full E2E test suite
LGP_API_KEY=your-key npx tsx src/scripts/test-e2e-pipeline.ts

# Run against a specific URL
LGP_API_KEY=your-key LGP_URL=https://api.leadgenius.app npx tsx src/scripts/test-e2e-pipeline.ts

# Preserve test data after execution
LGP_API_KEY=your-key npx tsx src/scripts/test-e2e-pipeline.ts --skip-cleanup

The test covers: auth → client management → settings verification → ICP creation → lead import/CRUD → lead search → lead generation → enrichment → copyright → scoring → task tracking → skill doc accuracy → pipeline analytics → campaigns → cleanup.

Documentation Site

Docsify-based docs are served at /docs (e.g., https://api.leadgenius.app/docs). Source files in /docs/, copied to public/docs-content/ at build time.