### Install and configure Apex MCP server locally

Source: https://apex.leadshark.io/docs/apex

Install the @leadshark/mcp-server package globally and set your API key as an environment variable for local use in Cursor or scripts.

```bash
npm install -g @leadshark/mcp-server
export LEADSHARK_API_KEY="sk_live_..."
```

--------------------------------

### Install @leadshark/mcp-server with npm

Source: https://apex.leadshark.io/docs/mcp

Install the LeadShark MCP server package. Requires Node.js 18+, a LeadShark Pro+ or Apex subscription, and an API key from Dashboard Settings.

```bash
npm install @leadshark/mcp-server
```

--------------------------------

### GET /api/automation-templates

Source: https://apex.leadshark.io/docs/api

Lists all automation templates on your account.

```APIDOC
## GET /api/automation-templates

### Description
List all automation templates on your account.

### Method
GET

### Endpoint
/api/automation-templates

### Response
#### Success Response (200)
- **templates** (array) - List of templates (first 20, newest first)

#### Response Example
{
  "templates": []
}

### Example Request
```
curl 'https://apex.leadshark.io/api/automation-templates' \
  -H "x-api-key: YOUR_API_KEY"
```
```

--------------------------------

### GET /api/v1/webhooks

Source: https://apex.leadshark.io/docs/api

Lists all webhooks for the authenticated account.

```APIDOC
## GET /api/v1/webhooks

### Description
Lists all webhooks for the authenticated account.

### Method
GET

### Endpoint
/api/v1/webhooks

### Response
#### Success Response (200)
- **webhooks** (array) - List of webhook objects (id, url, event_types)
```

--------------------------------

### GET /api/v1/discover

Source: https://apex.leadshark.io/docs/api

Fetches a feed of fresh lead-magnet posts for engagement, requiring an Apex subscription.

```APIDOC
## GET /api/v1/discover

### Description
A continuously refreshed feed of fresh lead-magnet posts from the LeadShark Lead Magnet Radar — prospect-rich posts to engage. Returns the public post, creator identity, and engagement counts only. Requires an Apex subscription.

### Method
GET

### Endpoint
/api/v1/discover
```

--------------------------------

### GET /api/leads

Source: https://apex.leadshark.io/docs/api

Retrieves a paginated list of leads. Use response.data for the current page and response.pagination.has_more to check for additional pages. Only non-archived, individual leads (LinkedIn profile IDs starting with ACo) are returned.

```APIDOC
## GET /api/leads

### Description
List all your leads (from automations and post engagement). Each lead includes its ICP Fit headline label and email (when present). Paginated for large lists.

### Method
GET

### Endpoint
/api/leads

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination. Defaults to 1.
- **limit** (integer) - Optional - Number of leads per page. Defaults to 250.

### Response
#### Success Response (200)
- **data** (array) - Current page of leads. Each item includes fields such as `id`, `name`, `title`, `linkedin_url`, `source`, `created_at`, `updated_at`, `commenter_id`, `post_id`, `linkedin_username`, `first_name`, `icp_headline_fit`, `icp_headline_pct`, `icp_headline_confidence`, `icp_headline_at`, `icp_score`, `lead_type`, `engagements`, `icp_fit`, `archived`, `enriched_profile`, `enriched_at`, `email`.
- **pagination** (object) - Pagination metadata. Contains `has_more` (boolean) indicating if there is a next page.

#### Response Example
{
  "data": [
    {
      "id": "uuid",
      "name": "string",
      "title": "string",
      "linkedin_url": "string",
      "source": "string",
      "created_at": "ISO 8601",
      "updated_at": "ISO 8601",
      "commenter_id": "string",
      "post_id": "string or null",
      "linkedin_username": "string or null",
      "first_name": "string or null",
      "icp_headline_fit": "string or null",
      "icp_headline_pct": "number or null",
      "icp_headline_confidence": "number or null",
      "icp_headline_at": "string or null",
      "icp_score": "number or null",
      "lead_type": "string",
      "engagements": [],
      "icp_fit": "string or null",
      "archived": "boolean",
      "enriched_profile": "object or null",
      "enriched_at": "string or null",
      "email": "string or null"
    }
  ],
  "pagination": {
    "has_more": false
  }
}
```

--------------------------------

### GET /api/bookmarks/tags

Source: https://apex.leadshark.io/docs/api

Retrieves all tags used on bookmarks.

```APIDOC
## GET /api/bookmarks/tags

### Description
Retrieve all tags used on bookmarks.

### Method
GET

### Endpoint
/api/bookmarks/tags

### Response
#### Success Response (200)
- **tags** (array) - List of tags

#### Response Example
{
  "tags": []
}
```

--------------------------------

### Creator Loadout markdown template

Source: https://apex.leadshark.io/docs/loadouts

The loadout.md template for a Creator tape, showing the YAML front matter with loadout type, tier, and MCP URL, followed by sections for the job description, setup questions, steps, approval gate, hard rules, and completion criteria. The approval gate travels with the file, requiring the agent to stop and show everything before any write.

```markdown
# Creator — Loadout

```yaml
loadout: content
tier: pro-plus            # Pro+ or above
mcp: https://apex.leadshark.io/mcp
```

**The job:** ...

## Before you run — ask the user
## Steps                  (See → Decide → Act, real tool names)
## STOP — approval gate   (no writes until the user approves)
## Never                  (hard rules the agent can't cross)
## Done means             (verifiable finish criteria)
```
```

--------------------------------

### GET /api/bookmarks

Source: https://apex.leadshark.io/docs/api

Retrieves all saved LinkedIn profiles.

```APIDOC
## GET /api/bookmarks

### Description
Retrieve all saved LinkedIn profiles.

### Method
GET

### Endpoint
/api/bookmarks

### Response
#### Success Response (200)
- **bookmarks** (array) - List of saved profiles

#### Response Example
{
  "bookmarks": []
}
```

--------------------------------

### GET /api/v1/invitations

Source: https://apex.leadshark.io/docs/api

Lists the LinkedIn connection requests people sent you. This is the REST twin of the `manage_invitations` MCP tool and runs the exact same logic. Available to Pro, Pro+, and Apex. Responding is a governed action: it follows your API key’s scope and your account’s safety mode (in queue mode responses are staged for your approval and you get `202`), and every response is recorded in your action log.

```APIDOC
## GET /api/v1/invitations

### Description
Lists the LinkedIn connection requests people sent you. This is the REST twin of the `manage_invitations` MCP tool and runs the exact same logic. Available to Pro, Pro+, and Apex. Responding is a governed action: it follows your API key’s scope and your account’s safety mode (in queue mode responses are staged for your approval and you get `202`), and every response is recorded in your action log.

### Method
GET

### Endpoint
/api/v1/invitations

### Parameters
#### Query Parameters
- **cursor** (string) - Optional - Pagination cursor for the next page of results.

### Response
#### Success Response (200)
- **invitations** (array) - List of pending invitations.
- **next_cursor** (string) - Cursor for the next page, if any.

#### Error Responses
- **400** - Bad Request - `invalid_cursor` - The cursor is invalid or expired.
- **401** - Unauthorized - `unauthorized` - Missing or invalid API key.
- **403** - Forbidden - `plan_required` - The account isn’t on Pro, Pro+, or Apex.
- **403** - Forbidden - `scope_denied` / `mode_too_low` - The key’s scope or the account’s safety mode doesn’t allow responding.
- **400** - Bad Request - `linkedin_not_connected` - No LinkedIn account connected to this workspace.
- **429** - Too Many Requests - `rate_limited` - API rate limit reached (see `details`).
- **500 / 502 / 504** - Server Error - `linkedin_provider_error` / `linkedin_timeout` - LinkedIn (or the connection lookup) couldn’t be reached. Safe to retry.

### Notes
- Result statuses per invitation: `accepted` / `ignored` (success), `already_accepted` / `already_ignored` (success), `already_processed` (not success), `not_found` (not success), `queued` (success, response `202`), `error` (not success), `skipped` (not success).
```

--------------------------------

### lead.sent event payload example

Source: https://apex.leadshark.io/docs/webhooks

Example payload for the `lead.sent` event, fired when a lead is pushed from the dashboard via "Send to webhook". This is a manual, user-triggered action, not LinkedIn-driven, so no `data.post` or `data.automation` blocks are present. Subscribe to `lead_sent` in Settings → Webhooks or via the REST API to receive it.

```json
{
  "event": "lead.sent",
  "timestamp": "2026-05-09T13:24:11.482Z",
  "data": {
    "lead": {
      "name": "Sarah Wilson",
      "first_name": "Sarah",
      "last_name": "Wilson",
      "title": "Content Marketing Specialist",
      "email": "sarah@example.com",
      "linkedin_url": "https://linkedin.com/in/sarah-wilson",
      "linkedin_username": "sarah-wilson",
      "commenter_id": "ACoAAEXAMPLE444555666",
      "connection_status": "Connected",
      "location": "San Francisco, CA",
      "icp_fit": null,
      "icp_score": 0.95,
      "icp_headline_fit": "fit"
    }
  }
}
```

--------------------------------

### Call Apex REST API with curl

Source: https://apex.leadshark.io/docs/apex

Use the REST API by passing your API key in the x-api-key header. This example fetches signals from the /api/v1/signals endpoint.

```bash
curl https://apex.leadshark.io/api/v1/signals \
  -H "x-api-key: sk_live_..."
```

--------------------------------

### GET /api/v1/links

Source: https://apex.leadshark.io/docs/api

Retrieves a list of all lead magnet links. Requires Pro+ or Apex subscription.

```APIDOC
## GET /api/v1/links

### Description
List all lead magnet links. Requires Pro+ or Apex subscription.

### Method
GET

### Endpoint
/api/v1/links

```

--------------------------------

### GET /api/v1/pages

Source: https://apex.leadshark.io/docs/api

Retrieves a list of all quiz pages. Requires Pro+ or Apex subscription.

```APIDOC
## GET /api/v1/pages

### Description
List all quiz pages. Requires Pro+ or Apex subscription.

### Method
GET

### Endpoint
/api/v1/pages

```

--------------------------------

### GET /api/post-stats

Source: https://apex.leadshark.io/docs/api

Deprecated endpoint for listing recent posts. Superseded by GET /api/v1/posts. Existing callers continue to work — the response carries a Deprecation: true header and a Link header pointing at the successor. Migrate at your convenience. Summary mode (?summary=true) is unaffected and remains the canonical home for aggregate post metrics.

```APIDOC
## GET /api/post-stats

### Description
Deprecated. Superseded by GET /api/v1/posts. Existing callers continue to work — the response carries a Deprecation: true header and a Link header pointing at the successor. Migrate at your convenience. Summary mode (?summary=true) is unaffected and remains the canonical home for aggregate post metrics.

### Method
GET

### Endpoint
/api/post-stats

### Response
#### Success Response (200)
- **Deprecation** (boolean) - true
- **Link** (string) - Points to the successor endpoint.

#### Response Example
{
  "Deprecation": true,
  "Link": "<https://api.example.com/api/v1/posts>; rel=\"successor-version\""
}
```

--------------------------------

### Signature Verification

Source: https://apex.leadshark.io/docs/webhooks

Example code to verify the HMAC-SHA256 signature of an incoming webhook payload.

```APIDOC
## Signature Verification

### Description
Verify the HMAC-SHA256 signature of an incoming webhook payload to ensure authenticity.

### Method
POST

### Endpoint
Webhook endpoint (provided by LeadShark)

### Parameters
#### Headers
- **X-Webhook-Signature** (string) - Required - HMAC-SHA256 signature of the payload.
- **X-Webhook-Event** (string) - Required - Event type.
- **Content-Type** (string) - Required - application/json

### Request Example
```javascript
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return signature === expected;
}
```

### Response
#### Success Response (200)
- **valid** (boolean) - Whether the signature matches.

#### Response Example
```json
{
  "valid": true
}
```
```

--------------------------------

### GET /api/scheduled-posts

Source: https://apex.leadshark.io/docs/api

Retrieves all scheduled LinkedIn posts.

```APIDOC
## GET /api/scheduled-posts

### Description
Retrieve all scheduled LinkedIn posts.

### Method
GET

### Endpoint
/api/scheduled-posts

### Response
#### Success Response (200)
- **posts** (array) - List of scheduled posts

#### Response Example
{
  "posts": []
}
```

--------------------------------

### POST /api/v1/posts/search

Source: https://apex.leadshark.io/docs/api

Live LinkedIn content search — posts that contain your keywords, by anyone. Distinct from GET /api/v1/posts (a known person's recent posts), GET /api/v1/discover (Lead Magnet Radar corpus), and POST /api/linkedin-search (people only). Each result's post_id drops into the engagement and comment/react endpoints.

```APIDOC
## POST /api/v1/posts/search

### Description
Live LinkedIn content search — posts that contain your keywords, by anyone. Distinct from GET /api/v1/posts (a known person's recent posts), GET /api/v1/discover (Lead Magnet Radar corpus), and POST /api/linkedin-search (people only). Each result's post_id drops into the engagement and comment/react endpoints.

### Method
POST

### Endpoint
/api/v1/posts/search

### Response
#### Success Response (200)
- **post_id** (string) - The LinkedIn post URN. Pass it to the engagement and comment/react endpoints.

#### Response Example
{
  "post_id": "urn:li:share:123456789"
}
```

--------------------------------

### GET /api/v1/invitations

Source: https://apex.leadshark.io/docs/webhooks

Polls for pending LinkedIn connection requests instead of relying on webhooks.

```APIDOC
## GET /api/v1/invitations

### Description
Polls for pending LinkedIn connection requests instead of relying on webhooks.

### Method
GET

### Endpoint
/api/v1/invitations

### Parameters
None

### Response
#### Success Response (200)
- **invitations** (array) - List of pending invitations.

#### Response Example
{
  "invitations": [
    {
      "id": "7384123456789012345",
      "message": "Hi, let's connect!",
      "requested_at": "2026-10-10T07:55:00.000Z"
    }
  ]
}
```

--------------------------------

### GET /api/v1/webhooks/:id

Source: https://apex.leadshark.io/docs/api

Retrieves a specific webhook by its ID.

```APIDOC
## GET /api/v1/webhooks/:id

### Description
Retrieves a specific webhook by its ID.

### Method
GET

### Endpoint
/api/v1/webhooks/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The webhook ID

### Response
#### Success Response (200)
- **id** (string) - Webhook ID
- **url** (string) - The configured URL
- **event_types** (array of strings) - Subscribed event types
```

--------------------------------

### GET /api/leads

Source: https://apex.leadshark.io/docs/api

Reads lead labels back on each lead, including ICP fit labels and percentages.

```APIDOC
## [GET] /api/leads

### Description
Reads lead labels back on each lead. Returns fields such as `icp_headline_fit` and `icp_headline_pct`.

### Method
GET

### Endpoint
/api/leads

### Response
#### Success Response (200)
- **icp_headline_fit** (string) - The ICP fit label (e.g., `fit`, `maybe`, `not`).
- **icp_headline_pct** (number) - The ICP headline percentage.
```

--------------------------------

### POST /api/v1/invitations

Source: https://apex.leadshark.io/docs/api

Accepts or ignores LinkedIn connection requests, one or many at a time. This is the REST twin of the `manage_invitations` MCP tool and runs the exact same logic. Available to Pro, Pro+, and Apex. Responding is a governed action: it follows your API key’s scope and your account’s safety mode (in queue mode responses are staged for your approval and you get `202`), and every response is recorded in your action log.

```APIDOC
## POST /api/v1/invitations

### Description
Accepts or ignores LinkedIn connection requests, one or many at a time. This is the REST twin of the `manage_invitations` MCP tool and runs the exact same logic. Available to Pro, Pro+, and Apex. Responding is a governed action: it follows your API key’s scope and your account’s safety mode (in queue mode responses are staged for your approval and you get `202`), and every response is recorded in your action log.

### Method
POST

### Endpoint
/api/v1/invitations

### Parameters
#### Request Body
- **action** (string) - Required - The action to perform: `accept` or `ignore`.
- **invitation_ids** (array of strings) - Required - List of invitation IDs to respond to. Must be between 1 and 50 items.

### Response
#### Success Response (200)
- **results** (array) - Per-invitation results with statuses.
- **next_cursor** (string) - Cursor for the next page, if any.

#### Success Response (202)
- **results** (array) - Per-invitation results with status `queued` and `pending_action_id`.

#### Error Responses
- **400** - Bad Request - `invalid_request` - Missing/unknown action, empty or more than 50 invitation_ids, limit out of range.
- **400** - Bad Request - `invalid_cursor` - The cursor is invalid or expired.
- **401** - Unauthorized - `unauthorized` - Missing or invalid API key.
- **403** - Forbidden - `plan_required` - The account isn’t on Pro, Pro+, or Apex.
- **403** - Forbidden - `scope_denied` / `mode_too_low` - The key’s scope or the account’s safety mode doesn’t allow responding.
- **400** - Bad Request - `linkedin_not_connected` - No LinkedIn account connected to this workspace.
- **429** - Too Many Requests - `rate_limited` - API rate limit reached (see `details`).
- **500 / 502 / 504** - Server Error - `linkedin_provider_error` / `linkedin_timeout` - LinkedIn (or the connection lookup) couldn’t be reached. Safe to retry.

### Notes
- Result statuses per invitation: `accepted` / `ignored` (success), `already_accepted` / `already_ignored` (success), `already_processed` (not success), `not_found` (not success), `queued` (success, response `202`), `error` (not success), `skipped` (not success).
- Error codes per invitation: `rate_limited`, `cooldown`, `invitation_unavailable`, `invitation_rejected`, `provider_error`.
- Moving from `POST /api/mcp/invitations`? Same data, same invitation ids, same governance. Replace `{ "action": "list" }` with `GET /api/v1/invitations`, and `{ "action": "accept" | "ignore", "invitation_ids": [...] }` with the same body on `POST /api/v1/invitations`. Differences: errors here are `{ error, code }`, lists paginate with `next_cursor`, and Pro keys work too. The MCP route keeps working unchanged for MCP clients.
```

--------------------------------

### GET /api/v1/dashboard-activity

Source: https://apex.leadshark.io/docs/api

Retrieves activity rollups for exports and reporting, with configurable granularity and date range filters.

```APIDOC
## GET /api/v1/dashboard-activity

### Description
Rollups of your automation activity for exports and reporting — comments processed, DMs, connections, replies, and leads — matching the main dashboard. Pick a granularity: daily, weekly, monthly, or all-time.

### Method
GET

### Endpoint
/api/v1/dashboard-activity

### Parameters
#### Query Parameters
- **after** (string) - Optional - Counts from that moment onward.
- **before** (string) - Optional - Stops before that instant (use the start of the day after your last day to include a full calendar day).
- **cutoff** (string) - Optional - Returns two slices — before and on/after — for side-by-side comparisons.
- **granularity** (string) - Optional - daily, weekly, monthly, or all_time. For granularity=all_time the window params are ignored.
```

--------------------------------

### GET /api/v1/links/:slug

Source: https://apex.leadshark.io/docs/api

Retrieves a specific lead magnet link by its slug. Requires Pro+ or Apex subscription.

```APIDOC
## GET /api/v1/links/:slug

### Description
Retrieve a specific lead magnet link by its slug. Requires Pro+ or Apex subscription.

### Method
GET

### Endpoint
/api/v1/links/:slug

### Parameters
#### Path Parameters
- **slug** (string) - Required - The slug of the lead magnet link.

```

--------------------------------

### GET /api/v1/pages/:id/responses

Source: https://apex.leadshark.io/docs/api

Retrieves responses for a specific quiz page. Requires Pro+ or Apex subscription.

```APIDOC
## GET /api/v1/pages/:id/responses

### Description
Retrieve responses for a specific quiz page. Requires Pro+ or Apex subscription.

### Method
GET

### Endpoint
/api/v1/pages/:id/responses

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the quiz page.

```

--------------------------------

### GET /api/v1/signals

Source: https://apex.leadshark.io/docs/api

Retrieves ranked hot leads with heat scores and engagement signals. Supports pagination via `page` and filtering by engagement date or capture date.

```APIDOC
## GET /api/v1/signals

### Description
Retrieves a list of ranked hot leads (signals) for the authenticated user. Each lead includes a composite heat score, signal counts, and recent engagement events.

### Method
GET

### Endpoint
/api/v1/signals

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination. Increment until `page < total_pages` is false.
- **since** (string, ISO 8601) - Optional - Filters by `signal_date` (engagement date).
- **until** (string, ISO 8601) - Optional - Filters by `signal_date` (engagement date).
- **since_captured** (string, ISO 8601) - Optional - Filters by `created_at` (when the row was inserted).
- **until_captured** (string, ISO 8601) - Optional - Filters by `created_at` (when the row was inserted).

### Response
#### Success Response (200)
- **signals** (array) - List of hot lead records. Each item includes:
  - **id** (string, UUID) - Hot lead record ID
  - **actor_name** (string) - Lead's full name
  - **actor_linkedin_id** (string) - LinkedIn member identifier
  - **actor_linkedin_url** (string) - LinkedIn profile URL
  - **actor_profile_picture_url** (string | null) - Profile picture URL
  - **heat_score** (number) - Composite engagement score (higher = hotter lead)
  - **signal_count** (number) - Total number of signal events from this lead
  - **signal_breakdown** (object) - Counts per signal type, e.g. `{ "comment": 5, "reaction": 3 }`
  - **top_signals** (array) - Recent signal events with `type`, `date`, and `source_url`
  - **connection_status** (string) - LinkedIn relationship: `FIRST_DEGREE`, `SECOND_DEGREE`, etc.
  - **first_seen_at** (string, ISO 8601) - When this lead first appeared in signals
  - **computed_at** (string, ISO 8601) - When the heat score was last computed
- **pagination** (object) - Pagination metadata. Use `total_pages` to know how many pages exist.

#### Response Example
```json
{
  "signals": [
    {
      "id": "uuid",
      "actor_name": "John Doe",
      "actor_linkedin_id": "linkedin-id",
      "actor_linkedin_url": "https://linkedin.com/in/johndoe",
      "actor_profile_picture_url": "https://example.com/photo.jpg",
      "heat_score": 85,
      "signal_count": 8,
      "signal_breakdown": { "comment": 5, "reaction": 3 },
      "top_signals": [
        { "type": "comment", "date": "2026-01-01T00:00:00Z", "source_url": "https://linkedin.com/post/123" }
      ],
      "connection_status": "SECOND_DEGREE",
      "first_seen_at": "2026-01-01T00:00:00Z",
      "computed_at": "2026-01-02T00:00:00Z"
    }
  ],
  "pagination": { "total_pages": 3 }
}
```
```

--------------------------------

### GET /api/v1/links/:slug/analytics

Source: https://apex.leadshark.io/docs/api

Retrieves analytics for a specific lead magnet link. Requires Pro+ or Apex subscription.

```APIDOC
## GET /api/v1/links/:slug/analytics

### Description
Retrieve analytics for a specific lead magnet link. Requires Pro+ or Apex subscription.

### Method
GET

### Endpoint
/api/v1/links/:slug/analytics

### Parameters
#### Path Parameters
- **slug** (string) - Required - The slug of the lead magnet link.

```

--------------------------------

### GET /api/post-stats?summary=true

Source: https://apex.leadshark.io/docs/api

One call returns lifetime totals across your last N posts (impressions, comments, reactions, reposts) without you having to paginate and sum yourself. Great for dashboards and weekly reports. Apex-gated because each call may walk multiple upstream pages.

```APIDOC
## GET /api/post-stats?summary=true

### Description
One call returns lifetime totals across your last N posts (impressions, comments, reactions, reposts) without you having to paginate and sum yourself. Great for dashboards and weekly reports. Apex-gated because each call may walk multiple upstream pages.

### Method
GET

### Endpoint
/api/post-stats?summary=true

### Query Parameters
- **summary** (boolean) - Required - Set to true to enable summary mode.

### Response
#### Success Response (200)
- **truncated** (boolean) - Indicates whether you hit max_posts before reaching the end of your post history.
- **next_cursor** (string) - Pass back as cursor to continue scanning when truncated is true.
- **impressions** (number) - Lifetime total impressions.
- **comments** (number) - Lifetime total comments.
- **reactions** (number) - Lifetime total reactions.
- **reposts** (number) - Lifetime total reposts.

#### Response Example
{
  "truncated": false,
  "next_cursor": null,
  "impressions": 12345,
  "comments": 123,
  "reactions": 456,
  "reposts": 78
}
```

--------------------------------

### GET /api/v1/pages/:id

Source: https://apex.leadshark.io/docs/api

Retrieves a specific quiz page by its ID. Requires Pro+ or Apex subscription.

```APIDOC
## GET /api/v1/pages/:id

### Description
Retrieve a specific quiz page by its ID. Requires Pro+ or Apex subscription.

### Method
GET

### Endpoint
/api/v1/pages/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the quiz page.

```

--------------------------------

### GET /api/v1/signals/events

Source: https://apex.leadshark.io/docs/api

Retrieves raw engagement signal events with detailed metadata. Supports pagination and filtering by engagement date or capture date.

```APIDOC
## GET /api/v1/signals/events

### Description
Retrieves raw engagement signal events for the authenticated user. Each event includes the signal type, weight, source, and metadata.

### Method
GET

### Endpoint
/api/v1/signals/events

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination. Increment until `page < total_pages` is false.
- **since** (string, ISO 8601) - Optional - Filters by `signal_date` (engagement date).
- **until** (string, ISO 8601) - Optional - Filters by `signal_date` (engagement date).
- **since_captured** (string, ISO 8601) - Optional - Filters by `created_at` (when the row was inserted).
- **until_captured** (string, ISO 8601) - Optional - Filters by `created_at` (when the row was inserted).

### Response
#### Success Response (200)
- **events** (array) - List of signal event records. Each item includes:
  - **id** (string, UUID) - Signal event record ID
  - **actor_linkedin_id** (string) - LinkedIn member identifier
  - **actor_name** (string) - Lead's full name
  - **actor_title** (string | null) - LinkedIn headline / job title
  - **actor_linkedin_url** (string) - LinkedIn profile URL
  - **signal_type** (string) - One of the signal types: `comment`, `reaction`, `repost`, `profile_view`, `lead_magnet_click`, `dm_sent`, `comment_reply`, `connection_accepted`, `connection_sent`, `automation_engagement`
  - **signal_weight** (number) - Weight of this signal toward heat score
  - **source_url** (string | null) - LinkedIn post or page URL that triggered the signal
  - **meta** (object) - Additional metadata (varies by signal type, e.g. `reaction_type` for reactions, `comment_text` for comments)
  - **signal_date** (string, ISO 8601) - When the engagement happened on LinkedIn. Day-truncated. For comments/DMs/clicks/connections this is the actual event date. For reactions and reposts, this is the day we first detected the actor (or the post's publish date for historical pre-Apr 2026 rows). Filterable via `since` / `until`.
  - **created_at** (string, ISO 8601) - When the row was first inserted into our database. Filterable via `since_captured` / `until_captured`.
- **pagination** (object) - Pagination metadata. Use `total_pages` to know how many pages exist.

#### Response Example
```json
{
  "events": [
    {
      "id": "uuid",
      "actor_linkedin_id": "linkedin-id",
      "actor_name": "John Doe",
      "actor_title": "CEO",
      "actor_linkedin_url": "https://linkedin.com/in/johndoe",
      "signal_type": "comment",
      "signal_weight": 10,
      "source_url": "https://linkedin.com/post/123",
      "meta": { "comment_text": "Great post!" },
      "signal_date": "2026-01-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ],
  "pagination": { "total_pages": 3 }
}
```
```

--------------------------------

### Example payload for new.comment webhook event

Source: https://apex.leadshark.io/docs/webhooks

Payload for the 'new.comment' webhook event, triggered when someone comments on your post.      Includes legacy fields like 'commenter_id' and 'post_id' for backward compatibility. The 'timestamp' and 'created_at' are in ISO 8601 format, and the payload version is currently 2.

```json
{
  "event": "new.comment",
  "timestamp": "2026-05-07T12:42:27.124Z",
  "payload_version": 2,
  "data": {
    "lead": {
      "name": "Sarah Wilson",
      "first_name": "Sarah",
      "title": "Content Marketing Specialist",
          "linkedin_url": "https://linkedin.com/in/sarah-wilson",
      "linkedin_username": "sarah-wilson",
      "connection_status": "2nd Connection",
      "actor_id": "ACoAAEXAMPLE444555666",

      // ── Legacy field (kept for back-compat) ──
      "commenter_id": "ACoAAEXAMPLE444555666"
    },
    "comment": {
      "id": "7371940875070795776",
      "text": "Great insights! Thanks for sharing.",
      "created_at": "2026-05-07T16:21:08.656Z"
    },
    "post": {
      "id": "urn:li:activity:7372270383585984512",
      "url": "https://www.linkedin.com/feed/update/urn:li:activity:7372270383585984512"
    },
    "automation": { "id": "uuid", "name": "Content Engagement" },

    // ── Legacy fields (kept for back-compat) ──
    "post_id": "urn:li:activity:7372270383585984512",
    "post_url": "https://www.linkedin.com/feed/update/urn:li:activity:7372270383585984512"
  }
}
```

--------------------------------

### GET /api/v1/posts/{post_id}/reactions

Source: https://apex.leadshark.io/docs/api

Retrieves the list of people who reacted to a specific LinkedIn post. Results are pulled live from the connected LinkedIn account.

```APIDOC
## GET /api/v1/posts/{post_id}/reactions

### Description
Retrieve the list of people who reacted to a specific LinkedIn post. Results are pulled live from the connected LinkedIn account.

### Method
GET

### Endpoint
/api/v1/posts/{post_id}/reactions

### Parameters
#### Path Parameters
- **post_id** (string) - Required - The LinkedIn activity URN or numeric id of the post. Obtain from /api/post-stats using the `social_id` field.

### Response
#### Success Response (200)
- **items** (array) - List of reaction records.
- **pagination** (object) - Pagination info with `cursor` (string|null) and `has_more` (boolean).

#### Response Example
{
  "items": [],
  "pagination": {
    "cursor": "abc123" | null,
    "has_more": true | false
  }
}

### Error Codes
- `invalid_post_id` (400) - `post_id` isn't a LinkedIn activity URN or numeric id.
- `invalid_cursor` (400) - `cursor` exceeds 4096 characters (reactions / comments only).
- `linkedin_not_connected` (400) - Workspace has no LinkedIn account connected.
- `linkedin_post_not_found` (404) - LinkedIn returned 404 for this post id.
- `apex_required` (403) - Only for `/profile-viewers` and `/followers`; reactions accept Pro & up.
```

--------------------------------

### GET /api/v1/links/:slug/events

Source: https://apex.leadshark.io/docs/api

Retrieves the raw event stream for a specific lead magnet link. Requires Pro+ or Apex subscription. Provides event details including click and email capture events.

```APIDOC
## GET /api/v1/links/:slug/events

### Description
Retrieve the raw event stream for a specific lead magnet link. Requires Pro+ or Apex subscription. For `event_type=click`, `email`/`name`/`phone` are always `null` (clicks don't capture contact info). For `event_type=email_capture`, both `email` and `commenter_id` are populated together. Construct the LinkedIn profile URL as `https://linkedin.com/in/{commenter_id}`. When `commenter_id` is `"anonymous"`, the visitor came through a generic share rather than a personalized redirect — there is no LinkedIn identity to join.

### Method
GET

### Endpoint
/api/v1/links/:slug/events

### Parameters
#### Path Parameters
- **slug** (string) - Required - The slug of the lead magnet link.

#### Query Parameters
- **event_type** (string) - Optional - Filter events by type (e.g., `click`, `email_capture`).

```

--------------------------------

### List Automation Templates with cURL

Source: https://apex.leadshark.io/docs/api

Use this cURL command to fetch the first 20 automation templates (newest first) from the LeadShark API. Requires an API key in the x-api-key header.

```bash
curl 'https://apex.leadshark.io/api/automation-templates' \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Configure LeadShark MCP server in Claude Desktop

Source: https://apex.leadshark.io/docs/mcp

Adds the LeadShark MCP server to Claude Desktop's claude_desktop_config.json so the connector runs locally. Requires a LEADSHARK_API_KEY value in place of your_key and a restart of Claude Desktop after editing.

```json
{
  "mcpServers": {
    "leadshark": {
      "command": "npx",
      "args": ["-y", "@leadshark/mcp-server"],
      "env": {
        "LEADSHARK_API_KEY": "your_key"
      }
    }
  }
}
```

--------------------------------

### Configure LeadShark MCP in Cursor (.cursor/mcp.json)

Source: https://apex.leadshark.io/docs/mcp

Create `.cursor/mcp.json` with this configuration to enable the LeadShark MCP server in Cursor. The LEADSHARK_API_KEY environment variable is resolved from your shell environment. Restart Cursor after adding the file.

```json
{
  "mcpServers": {
    "leadshark": {
      "command": "npx",
      "args": ["-y", "@leadshark/mcp-server"],
      "env": {
        "LEADSHARK_API_KEY": "${LEADSHARK_API_KEY}"
      }
    }
  }
}
```

--------------------------------

### Create a Page with Pages API

Source: https://apex.leadshark.io/docs/api

Creates and publishes a lead magnet page. Save the `page.id` from the response for later use.

```bash
curl -X POST 'https://apex.leadshark.io/api/v1/pages' \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "LinkedIn Growth Playbook",
    "status": "published",
    "page_title": "Get Your Free Playbook",
    "page_description": "The exact strategies I used to grow to 100K followers",
    "questions": [{
      "question_text": "What is your biggest LinkedIn challenge?",
      "answers": [
        { "answer_text": "Getting more engagement", "mapped_outcome": "fit" },
        { "answer_text": "Growing my network", "mapped_outcome": "fit" },
        { "answer_text": "Just browsing", "mapped_outcome": "not" }
      ]
    }]
  }'
```

--------------------------------

### Connect to Apex via MCP client

Source: https://apex.leadshark.io/docs/apex

Add the Apex MCP server to Claude.ai, ChatGPT, or any MCP client by providing this URL.

```text
https://apex.leadshark.io/mcp
```

--------------------------------

### POST /api/v1/links

Source: https://apex.leadshark.io/docs/api

Creates a new lead magnet link. Requires Pro+ or Apex subscription.

```APIDOC
## POST /api/v1/links

### Description
Create a new lead magnet link. Requires Pro+ or Apex subscription.

### Method
POST

### Endpoint
/api/v1/links

```

--------------------------------

### Calculate new likes via snapshot diff

Source: https://apex.leadshark.io/docs/api

Pseudo-code showing how to compute new likes by subtracting yesterday's reactor set from today's. The reactions endpoint lacks per-like timestamps, so a daily snapshot diff is required.

```pseudocode
NEW_LIKES = reactors_today − reactors_yesterday   // per post_id
```

--------------------------------

### POST /api/v1/links

Source: https://apex.leadshark.io/docs/api

Creates a lead-magnet link. Pass the `automation_id` and `page_id` to route the automation's DMs/comments through that page.

```APIDOC
## [POST] /api/v1/links

### Description
Creates a lead-magnet link. Pass the `automation_id` and `page_id` to route the automation's DMs/comments through that page.

### Method
POST

### Endpoint
/api/v1/links

### Parameters
#### Request Body
- **automation_id** (string) - Required - The automation ID.
- **page_id** (string) - Required - The page ID.

### Response
#### Success Response (200)
- **id** (string) - The link ID.
```

--------------------------------

### GET /api/v1/followers

Source: https://apex.leadshark.io/docs/api

Retrieves the list of your LinkedIn followers. This endpoint requires an Apex subscription.

```APIDOC
## GET /api/v1/followers

### Description
Retrieve the list of your LinkedIn followers. This endpoint requires an Apex subscription.

### Method
GET

### Endpoint
/api/v1/followers

### Parameters
#### Query Parameters
- **source** (string) - Optional - Default `recent` reads "started following you" notification cards. Use `source=list` for bulk export.

### Response
#### Success Response (200)
- **items** (array) - List of follower records. May include `follower_count` on the first page.
- **pagination** (object) - Pagination info with `cursor` (string|null) and `has_more` (boolean).

#### Response Example
{
  "items": [],
  "pagination": {
    "cursor": "abc123" | null,
    "has_more": true | false
  }
}

### Error Codes
- `linkedin_not_connected` (400) - Workspace has no LinkedIn account connected.
- `apex_required` (403) - API key's subscription is not Apex.
```

--------------------------------

### POST /api/v1/pages

Source: https://apex.leadshark.io/docs/api

Creates a Page. Pages attach to lead-magnet links, not directly to automations.

```APIDOC
## [POST] /api/v1/pages

### Description
Creates a Page. Pages attach to lead-magnet links, not directly to automations.

### Method
POST

### Endpoint
/api/v1/pages

### Response
#### Success Response (200)
- **id** (string) - The page ID.
```

--------------------------------

### Create webhook-only automation with curl

Source: https://apex.leadshark.io/docs/api

Creates an automation that performs no LeadShark-side actions but streams comments to webhooks. Requires only name, post_id, and linkedin_post_url. Defaults: keywords: [], dm_template: "", auto_connect: false, auto_like: false, status: "Running".

```bash
curl -X POST 'https://apex.leadshark.io/api/automations' \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "Webhook only — Q1 lead magnet",
    "post_id": "urn:li:activity:7150123456789012345",
    "linkedin_post_url": "https://www.linkedin.com/posts/..."
  }'
```

--------------------------------

### POST /api/v1/pages

Source: https://apex.leadshark.io/docs/api

Creates a new quiz page. Requires Pro+ or Apex subscription.

```APIDOC
## POST /api/v1/pages

### Description
Create a new quiz page. Requires Pro+ or Apex subscription.

### Method
POST

### Endpoint
/api/v1/pages

```

--------------------------------

### GET /api/v1/pages/:id/stats

Source: https://apex.leadshark.io/docs/api

Retrieves statistics for a specific quiz page. Requires Pro+ or Apex subscription.

```APIDOC
## GET /api/v1/pages/:id/stats

### Description
Retrieve statistics for a specific quiz page. Requires Pro+ or Apex subscription.

### Method
GET

### Endpoint
/api/v1/pages/:id/stats

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the quiz page.

```

--------------------------------

### Register LeadShark MCP server with Claude Code CLI

Source: https://apex.leadshark.io/docs/mcp

Adds the LeadShark MCP server to Claude Code using the `claude mcp add` command with stdio transport. Requires a LeadShark API key passed via the LEADSHARK_API_KEY environment variable.

```bash
claude mcp add leadshark \
  --transport stdio \
  --env LEADSHARK_API_KEY=your_key \
  -- npx -y @leadshark/mcp-server
```