API & MCP reference

Base URL and authentication

curl https://mcp.linkedminds.in/v1/me \
-H "Authorization: Bearer lm_YOUR_REST_API_KEY"

Generate the key in Settings → API Key under REST API Key. It is shown once. Rotating or revoking it takes effect immediately. GET /v1 needs no key and lists every endpoint.

Example: pause a campaign and read its leads

# Pause it
curl -X PATCH https://mcp.linkedminds.in/v1/campaigns/$CAMPAIGN_ID \
-H "Authorization: Bearer $LM_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"paused"}'

# Read the leads that accepted
curl "https://mcp.linkedminds.in/v1/campaigns/$CAMPAIGN_ID/leads?state=CONNECTED&limit=100" \
-H "Authorization: Bearer $LM_KEY"

Example: push your own leads in

This is how a sheet, a CRM or an n8n / Zapier / Make workflow feeds a campaign. Send LinkedIn profile URLs; anything you know about the person is optional and only used until we enrich the profile ourselves. Adding a lead never sends anything on its own - the campaign has to be running, and every message still passes the same daily caps, warm-up phase and ban-risk checks.

# The short form - just URLs
curl -X POST https://mcp.linkedminds.in/v1/campaigns/$CAMPAIGN_ID/leads \
-H "Authorization: Bearer $LM_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":[
      "https://www.linkedin.com/in/some-person/",
      "https://www.linkedin.com/in/another-person/"
    ]}'

# The long form - carry what you already know
curl -X POST https://mcp.linkedminds.in/v1/campaigns/$CAMPAIGN_ID/leads \
-H "Authorization: Bearer $LM_KEY" \
-H "Content-Type: application/json" \
-d '{"leads":[
      {"linkedin_url":"https://www.linkedin.com/in/some-person/",
       "first_name":"Priya","current_company":"Acme","current_title":"Head of Growth"}
    ]}'

# With your own merge fields - used in messages as {{c_first_line}} and {{c_role}}
curl -X POST https://mcp.linkedminds.in/v1/campaigns/$CAMPAIGN_ID/leads \
-H "Authorization: Bearer $LM_KEY" \
-H "Content-Type: application/json" \
-d '{"leads":[
      {"linkedin_url":"https://www.linkedin.com/in/some-person/",
       "custom_variables":{
         "first_line":"Congrats on the $12M round",
         "role":"Senior Backend Engineer"}}
    ]}'

# 202 Accepted
# {"data":{"added":1,"duplicates":0,"invalid":[],"invalid_count":0,
#          "campaign_leads":42,"plan_limit":10000,
#          "custom_variables_saved":1,"custom_variables_failed":0,
#          "custom_variables_rejected":[]}}

• 200 leads per call. Split a bigger list across calls; the writes-per-minute budget below paces them.
• Safe to retry. A lead already on the campaign is reported under duplicates and left exactly as it is - re-importing never restarts someone mid-conversation.
• Bad URLs do not fail the call. Anything that is not a LinkedIn profile URL comes back in invalid while the rest are added. Only a request where every row is invalid returns 422.
• Leads per campaign are capped at 10,000 on Pro and 50,000 on Enterprise. Past that the call returns 422 campaign_lead_limit rather than importing part of the batch.

Custom variables

The API version of the extra columns in a CSV import. Anything you know that LinkedIn does not - an opening line, the role you are hiring for, a renewal month - goes in custom_variables on the lead, and your messages reference it with a c_ prefix: {"role": "..."} is {{c_role}} in a template. The prefix is what stops a variable called company from changing what {{company}} means.

• Names are lowercase letters, digits and underscores, up to 64 characters, sent without the c_. Up to 20 per lead, 500 characters per value. Numbers are stored as text.
• Nothing is dropped silently. A name we cannot store, or a value that is an object, a list or true/false, is skipped and listed in custom_variables_rejected while the lead is still added.
• Sending custom_variables replaces the lead's whole set, the same as re-importing a CSV with those columns. Leaving the field out keeps what the lead already has, so a plain retry never erases anything.
• Check what was stored with GET /v1/campaigns/{id}/leads - each lead carries its custom_variables.
• A variable a lead does not have renders as blank, exactly like a built-in with no value. They are private to your workspace and never shared with anyone else targeting the same person.

Rate limits

Three separate budgets, because the three kinds of call cost very different things. A read is free and carries no LinkedIn risk. A write changes your workspace. An action - a reply or a withdrawal - puts real work on a real LinkedIn account, so it is measured over an hour rather than a minute.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and the same pair prefixed X-RateLimit-Actions- for the hourly budget, so you can pace yourself rather than discover the ceiling by hitting it. A 429 carries Retry-After in seconds - wait that long rather than retrying in a tight loop.

Retries and duplicate sends

A 202 means the work is queued, not delivered. If a call times out you can safely retry it: an identical message to the same conversation within two minutes is treated as the retry it almost certainly is and comes back "deduplicated": true without sending again. A message a recipient has already seen cannot be unsent, so this errs towards sending once.

If the action cannot be queued at all - the account is disconnected, has no working proxy, or is not usable for that job - you get a 409 with the reason, and nothing is recorded as sent. A 502 means the queue itself was unreachable and nothing was queued; retry it.

Responses, paging and errors

List endpoints return { "data": [...], "limit": n, "offset": n } and single objects return { "data": {...} }. Anything that queues LinkedIn work returns 202 - queued, not yet sent. Errors are always { "error": { "code": "...", "message": "..." } }, and the message is written to be shown to a human as-is.

How the API is protected

• Keys are stored only as bcrypt hashes (rounds 12) - we cannot read yours back, and a rotate or revoke kills the old one immediately, not after a cache expires.
• Twenty rejected keys from one IP in five minutes blocks that IP for the rest of the window, so guessing a key is not something you can do at speed.
• Filter values are checked against a fixed list, IDs must be UUIDs, arrays are capped, paging is clamped and bodies over 64 KB are refused.
• Every request is scoped to your own client ID in the query itself. Another customer's campaign or conversation returns 404 - the same answer as one that does not exist, so the API cannot be used to find out who else is on the platform.
• Responses carry an explicit field list. Credentials, cookies, TOTP seeds and internal audit fields are never in a payload, on any endpoint.
• Every write is recorded to your audit log with the endpoint and the campaign it touched.

If we think a key has leaked, we disable it and tell you

The same watch runs on both credentials - the REST key and the Claude MCP client secret. It reacts to two different things, in two deliberately different ways:

• Repeated wrong secrets against your key (twelve in fifteen minutes). Neither key can realistically be guessed - they are 32 random bytes - so this means someone has seen the first part of a real key, in a screenshot, a log or a committed file. If that leaked, the rest may have. We disable the key, email you and post it to the bell, and Settings shows what happened. Generating a new key clears it. Nothing else is touched: campaigns, LinkedIn accounts and data carry on.
• One valid key used from an unusual number of places (25+ IP addresses in an hour). We only tell you - we do not disable it. That pattern is what a leaked key looks like, but it is also just what a serverless integration looks like, and killing a working production automation on that evidence would be the worse mistake. You decide whether to rotate.

Rotating is always safe and always available - it takes effect immediately rather than when a cache expires.

Using it from n8n

Yes - the REST key is exactly what n8n needs, and no LinkedMinds-specific node is required. Add an HTTP Request node, set Authentication to Generic Credential Type → Header Auth, and store the key as a credential so it never sits in the workflow JSON:

Name:   Authorization
Value:  Bearer lm_your_key_here

Method: GET
URL:    https://mcp.linkedminds.in/v1/conversations?unread=true

The same applies to Zapier (Webhooks by Zapier → Custom Request) and Make (HTTP module). Three things worth setting up front, because they are what breaks these workflows:

• Do not poll every minute. A schedule of five minutes or more sits comfortably inside the per-minute budget even with several workflows running.
• Turn on retry-on-fail with a wait, and honour Retry-After. n8n's default retry is immediate, which just spends the rest of your budget.
• A 202 is queued, not sent. If a branch depends on the message having actually gone out, read it back from /v1/conversations/{deal_id} rather than assuming.