API Reference

Programmatic access to your leads, products, and scans. Available on Pro and Agency plans.

Base URLhttps://leadsrover.io

Authentication

All requests require a Bearer token. Create API keys in Settings > API.

curl -H "Authorization: Bearer lr_sk_..." \
  https://leadsrover.io/api/v1/leads

Keys have scopes: read (default) for GET requests, and write for mutations. Max 5 keys per account, revokable instantly.

Response format

All responses use a JSON envelope.

Success

{
  "data": { ... }
}

Error

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Lead not found",
    "doc_url": "https://leadsrover.io/docs/api#errors"
  }
}

Paginated endpoints include a pagination object with total, limit, offset, and hasMore.

Rate limits

Read (GET)1,000 req / min

Write (PATCH, POST)60 req / min

Exceeding the limit returns 429 with a RATE_LIMITED error code.

Errors

400BAD_REQUESTInvalid parameters

401UNAUTHORIZEDMissing or invalid API key

403FORBIDDENInsufficient scope or plan

404NOT_FOUNDResource not found or not owned by you

409CONFLICTResource conflict (e.g. scan running)

429RATE_LIMITEDToo many requests

500INTERNAL_ERRORServer error

GET/api/v1/me

Returns your account info and current plan.

{
  "data": {
    "user": {
      "id": "abc123",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "timezone": "America/New_York",
      "createdAt": "2026-01-15T10:30:00.000Z"
    },
    "plan": {
      "type": "pro",
      "status": "active",
      "currentPeriodEnd": "2026-04-15T10:30:00.000Z",
      "limits": {
        "maxProducts": 25,
        "scansPerMonth": 2000,
        "aiCommentsPerMonth": 1000
      }
    }
  }
}

GET/api/v1/products

Lists all your products.

{
  "data": [
    {
      "id": 42,
      "name": "Acme CRM",
      "url": "https://acme.com",
      "pain": "Manual lead tracking is slow",
      "solution": "AI-powered CRM for small teams",
      "targetUsers": "Solo founders and small sales teams",
      "isActive": true,
      "createdAt": "2026-02-01T08:00:00.000Z",
      "updatedAt": "2026-03-20T14:30:00.000Z"
    }
  ]
}

GET/api/v1/products/:id

Returns a single product by ID. Same shape as the list endpoint.

POST/api/v1/products/:id/scan

Trigger an on-demand scan. Requires write scope. Counts toward your scan quota. Scans run asynchronously.

Response (202)

{
  "data": {
    "productId": 42,
    "status": "scanning",
    "message": "Scan enqueued successfully"
  }
}

GET/api/v1/leads

Lists leads across all products with filtering and pagination.

productId

number

Filter by product ID

status

string

Filter: new, contacted

minQuality

number

Minimum quality score (0-100)

since

ISO 8601

Only leads discovered after this date

sort

string

Sort by: discoveredAt (default), qualityScore

order

string

Sort order: desc (default), asc

limit

number

Results per page (1-100, default 50)

offset

number

Pagination offset (default 0)

Example

curl -H "Authorization: Bearer lr_sk_..." \
  "https://leadsrover.io/api/v1/leads?minQuality=70&status=new&limit=10"

Response

{
  "data": [
    {
      "id": 1234,
      "productId": 42,
      "subreddit": "smallbusiness",
      "redditPostId": "t3_abc123",
      "title": "Need a CRM that doesn't cost a fortune",
      "authorUsername": "startup_jane",
      "postUrl": "https://reddit.com/r/smallbusiness/...",
      "qualityScore": 85,
      "intent": "Looking for affordable CRM for 3-person team",
      "upvotes": 12,
      "commentCount": 8,
      "postedAt": "2026-03-27T14:30:00.000Z",
      "discoveredAt": "2026-03-27T15:00:00.000Z",
      "status": "new",
      "contactedAt": null,
      "language": "en"
    }
  ],
  "pagination": {
    "total": 47,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

GET/api/v1/leads/:id

Returns a single lead with its full post content. Same shape as the list endpoint, plus a content field with the full Reddit post body.

PATCH/api/v1/leads/:id

Update a lead's status. Requires write scope.

Request

{
  "status": "contacted"
}

Response

{
  "data": {
    "id": 1234,
    "status": "contacted"
  }
}

Valid statuses: new contacted

GET/api/v1/products/:id/leads

Lists leads for a specific product. Same filters as GET /leads except productId.