LeadPanther API Overview#

LeadPanther API v1 is available to accounts with active billing. API keys can be created and managed from Dashboard Settings -> Developer. Suspended, past-due, canceled, unpaid, and incomplete accounts cannot create or use API keys. API keys are bearer tokens. Keep them server-side and never expose them in browser code.

The canonical base URL is:

https://app.leadpanther.ai/api/v1

https://api.leadpanther.ai/v1 is not the LeadPanther app API base URL.

Current Capabilities#

API v1 supports:

• Reading API key subject information.
• Listing accessible client accounts.
• Creating, reading, updating, and deleting draft or scheduled posts.
• Updating the live text of eligible published LinkedIn posts and deleting eligible published LinkedIn posts.
• Reading post engagement metrics.
• Creating, reading, updating, and archiving lead magnets.
• Reading lead magnet analytics.
• Creating signed media upload URLs and deleting uploaded media.
• Listing leads.
• Listing inbound activity.
• Scheduling workspace member comment and repost actions for enabled workspaces.

Do not guess endpoint names. Use only documented paths under https://app.leadpanther.ai/api/v1. Generic paths such as /accounts, /users, /lists, /campaigns, /organizations, /team, /workspaces, and /lead-magnet-posts are not API v1 endpoints. The only documented workspace path is /workspaces/{workspaceId}/social-actions.

Authentication#

Send your API key in the Authorization header:

Authorization: Bearer lp_live_REDACTED

Supported key prefixes are lp_live_ and lp_test_.

All authenticated endpoints require a valid API key. Most endpoints also require a specific scope. The * scope satisfies any required scope.

Direct And Agency Access#

Direct-user routes operate on the API key owner's account:

/posts
/lead-magnets
/leads
/activity

Agency client work uses nested client routes:

/clients/{clientId}/posts
/clients/{clientId}/lead-magnets
/clients/{clientId}/leads
/clients/{clientId}/activity

For agency access, use the nested client routes. A valid agency API key alone is not enough; the agency must also have an active grant for the target client account.

In API v1, clientId is the client account user_id. Use values returned by GET /clients; do not use account table IDs, API key IDs, key hashes, or private database fields.

Workspace social actions use:

/workspaces/{workspaceId}/social-actions

This route is not an agency-client route and does not use clientId.

Modify Or Delete A Published LinkedIn Post#

Published LinkedIn mutations are capability-driven. Do not infer availability from a post status, LinkedIn URL, or stored provider identifier.

1. Fetch the post with GET /posts/{id} for a direct user or GET /clients/{clientId}/posts/{id} for an agency client.
2. Read data.published_mutation_capabilities from that response.
3. Update text only when can_edit is true. Send a unique Idempotency-Key and echo the returned opaque etag in X-LeadPanther-Post-ETag.
4. Delete only when can_delete is true. Send a unique Idempotency-Key and require explicit user confirmation because deletion cannot be undone.

Direct-user text update:

curl "https://app.leadpanther.ai/api/v1/posts/00000000-0000-4000-8000-000000000002" \
  -X PATCH \
  -H "Authorization: Bearer lp_live_REDACTED" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 00000000-0000-4000-8000-000000000003" \
  -H 'X-LeadPanther-Post-ETag: lp-post-REDACTED' \
  -d '{"text":"Updated LinkedIn post text."}'

Direct-user published deletion:

curl "https://app.leadpanther.ai/api/v1/posts/00000000-0000-4000-8000-000000000002" \
  -X DELETE \
  -H "Authorization: Bearer lp_live_REDACTED" \
  -H "Idempotency-Key: 00000000-0000-4000-8000-000000000004"

Agency actors use the same contract on the nested client route:

PATCH  /clients/{clientId}/posts/{id}
DELETE /clients/{clientId}/posts/{id}

Both operations require posts:write. An agency key also requires an active grant and activation for the target client. The API resolves the post under that client account; an agency key cannot use these routes to mutate another client or the agency owner's own post.

Published text updates never add, replace, reorder, or remove attached media. A post can be delete-capable even when its text is not edit-capable. Deleting a published post removes it from LinkedIn, including its comments and reactions, then removes its LeadPanther record, tracking, and active automation.

Reuse an idempotency key only to replay the exact same request. If a response returns provider_state_refreshed or stale_provider_version, fetch the post again, show the refreshed text to the user, and require a new review before retrying with the new etag and a new mutation intent.

Response Format#

Success responses use a data envelope:

{
  "data": {
    "name": "LeadPanther API",
    "version": "v1"
  },
  "request_id": "req_000000000000000000000001"
}

List responses include pagination:

{
  "data": [],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "request_id": "req_000000000000000000000002"
}

Error responses include a stable error code and message:

{
  "error": {
    "code": "forbidden",
    "message": "API key is missing a required scope."
  },
  "request_id": "req_000000000000000000000003"
}

Use the response request_id when contacting LeadPanther support about an API call.

Pagination#

All list endpoints use limit and offset pagination. Unless otherwise documented, limit defaults to 50 and is capped at 100.

GET /posts?limit=25&offset=0

Canonical pagination loop:

1. Start with offset=0.
2. Keep limit and all filters the same for the full export.
3. Read pagination.has_more from the response.
4. If has_more is true, add the returned pagination.limit to the current offset and request the next page.
5. If a page fails, retry the same offset; do not advance until that page succeeds.

Lead magnet analytics uses the same style for recent capture references.

Error Codes#

API v1 can return these error codes:

• bad_request
• unauthorized
• forbidden
• not_found
• conflict
• method_not_allowed
• not_implemented
• internal_error

If a call returns 403, check the API key scope and the route authorization model. Agency routes also require an active agency-client grant. Workspace social action routes require active workspace membership or an active workspace API grant.

Data Sensitivity#

Public examples in these docs are redacted and do not represent the full sensitivity of production data.

The leads:read scope can return personal data, including lead email fields and profile references. The activity:read scope can return message or comment content and platform identifiers. Store, process, and share responses according to your privacy and compliance obligations.

Current Limitations#

These features are planned or future-facing and are not currently available as a public API v1 contract:

• Published rate-limit semantics.
• Guaranteed idempotency key behavior for endpoints that do not explicitly document it.
• Webhook endpoints.
• Generated SDKs.
• A public changelog and deprecation policy.

Do not use Supabase REST, Supabase storage URLs, or api.leadpanther.ai as the app API unless LeadPanther support explicitly directs you to an internal integration path.

Endpoint Summary#

Agency equivalents use /clients/{clientId}/... for posts, lead magnets, media, leads, activity, and post boosts (/clients/{clientId}/posts/{id}/boost).