API and webhooks
Change your pages from scripts and AI assistants with the REST API and MCP server, and send new subscribers, form replies and sales to other tools.
Updated
Linkdeck has three tools for connecting your pages to other software:
- The REST API lets a script, an automation tool or an AI agent read and change your pages, for example to add a link every time you post a new video.
- The MCP server lets AI assistants such as Claude and ChatGPT work on your pages when you ask them to in a chat, for example "add a link to my new video" or "how many people clicked my links last week?".
- Webhooks send events from your page to another tool as they happen, for example to add every new subscriber to a spreadsheet through Zapier or Make.
You don't need to write code to use webhooks with Zapier or Make. The API is for people comfortable with HTTP requests.
REST API
Create an API key
- Click Account in the sidebar and scroll to API keys.
- Type a name for the key, such as "Zapier", so you know what uses it.
- Click Create key.
- Copy the key from the Your new API key window and store it somewhere safe.
The key starts with ld_. It's shown only once. If you lose it, create a new key and revoke the old one.
A key acts as you, for every profile on your account. Treat it like a password and don't put it in code that other people can see. You can have up to 20 keys. The list shows each key's name, its first few characters, when it was created and when it was last used.
To revoke a key, click the bin icon next to it and confirm. Anything using that key stops working straight away.
Only the account owner can create keys. People signed in with a login link can't.
Make a request
- Base URL: your Linkdeck address followed by
/api/v1. The exact address is shown as Base URL under API documentation in the API keys section. - Authentication: send your key in a header:
Authorization: Bearer ld_your_key. - Format: requests and responses are JSON.
- Rate limit: 30 requests per minute per key.
This example lists your profiles, then adds a link to one of them. Replace the values in the first two lines with your own.
BASE="paste the Base URL from your Account screen"
KEY="ld_your_key"
curl "$BASE/profiles" \
-H "Authorization: Bearer $KEY"
curl -X POST "$BASE/profiles/PROFILE_ID/blocks" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"type":"link","data":{"title":"My new video","url":"https://youtube.com/watch?v=..."}}'
Use the id of a profile from the first response in place of PROFILE_ID. New links are added to your page straight away.
Main endpoints
All paths are relative to the base URL. :id is a profile's ID.
| Method | Path | What it does |
|---|---|---|
GET |
/profiles |
List your profiles |
POST |
/profiles |
Create a profile: { username, display_name?, bio? } |
GET |
/profiles/:id |
A profile with its tabs and blocks |
PATCH |
/profiles/:id |
Update display_name, bio, avatar_url, socials, theme, settings or published |
DELETE |
/profiles/:id |
Delete a profile |
POST |
/profiles/:id/blocks |
Add a block: { type, data, style?, schedule?, tab_id?, parent_id? } |
PATCH |
/profiles/:id/blocks/:blockId |
Update a block's data, style, schedule or enabled |
DELETE |
/profiles/:id/blocks/:blockId |
Delete a block |
POST |
/profiles/:id/blocks/reorder |
Reorder blocks: { items: [{ id, tab_id?, parent_id? }] } |
POST |
/profiles/:id/tabs |
Add a tab: { title } |
GET |
/profiles/:id/analytics |
Stats. Add ?from=&to= in milliseconds, or from=all. The default is the last 30 days |
GET |
/profiles/:id/subscribers |
Your mailing list. Add ?format=csv for a CSV file |
GET |
/profiles/:id/submissions |
Form submissions. Add ?format=csv for a CSV file |
GET |
/profiles/:id/link-health |
The last check of each link |
GET |
/profiles/:id/versions |
Saved versions and scheduled launches |
POST |
/profiles/:id/versions |
Save the current page as a version: { label? } |
GET |
/profiles/:id/summary |
Last week's summary in plain English, with the numbers |
GET |
/profiles/:id/pages |
Your web pages |
GET |
/profiles/:id/products |
Your products, with views in the last 30 days, sales and earnings |
POST |
/profiles/:id/products |
Add a draft product: { title, price_cents? } |
PATCH |
/profiles/:id/products/:productId |
Update a product, for example { price_cents, published } |
GET |
/profiles/:id/orders |
Sales and downloads. Add ?format=csv for a CSV file, or ?product= for one product |
GET |
/qr |
List your QR codes |
POST |
/qr |
Create a QR code: { name, target_url, style? } |
GET |
/short-links |
List your short links with their click counts |
POST |
/short-links |
Create a short link: { target_url, code?, title?, profile_id?, pixels?, utm?, rules?, expires_at?, expired_url? } |
PATCH |
/short-links/:id |
Change a short link, with any of the same fields |
GET |
/short-links/:id/stats |
Clicks per day and the top referrers, countries and devices. Add ?from= (milliseconds) to change the start |
GET |
/short-links/export.csv |
All your short links as a CSV file |
Block types are link, header, text, embed, image, subscribe, form, file, folder, faq, testimonial, divider, product (data { productId, layout }, where layout is card or button), messenger, countdown, discount, donate, quote, timeline, resume, marquee, shop, booking, socials, postgrid and feed (data { kind, source, count?, layout? }, where kind is youtube, blog, podcast or etsy; the items are filled in when you save). The developer docs list every endpoint and each block type's fields, including discount codes, bookings, email campaigns, email service sync, the social planner, the Instagram inbox, short links, the media kit and AI tools.
Errors
When something goes wrong, the response has an HTTP error status and a JSON body like { "error": "Invalid API key." }. The ones you're most likely to see:
| Status | Meaning |
|---|---|
401 |
The key is missing, doesn't start with ld_, or has been revoked |
402 |
Editing is locked, because your trial ended without a plan or the profile is over your plan's limit. Reading still works |
429 |
You've sent more than 30 requests in a minute with this key. Wait and try again |
See Plans and billing for when editing locks.
Full reference and OpenAPI spec
Every endpoint, with its fields, an example and a Try it form, is on the developer docs page. Paste your key into the box at the top of that page to send real requests from your browser. The key stays in that browser tab only and is gone when you leave or reload the page.
A machine-readable description of the API (OpenAPI 3.1) is at your Linkdeck address followed by /api/v1/openapi.json. It's public, so tools that read OpenAPI specs, such as API clients, code generators and custom GPT actions, can load it without a key. Requests to the API itself still need your key.
Use Linkdeck from AI assistants
Linkdeck has an MCP server, so you can ask an AI assistant to work on your pages in a chat. MCP (Model Context Protocol) is the standard way AI apps connect to other services. Once it's connected, you can ask things like "Add a link to my new video at the top of my page", "Which links got the most clicks this month?" or "Make my preset pack free for an email".
The easiest way to connect is to sign in: add https://your-linkdeck-address/mcp to the AI app, and it opens a Linkdeck page where you sign in and approve access. You choose which profiles it can use, and whether it can only read or can also make changes. Whatever you choose, assistants can draft emails and posts but never send emails, publish posts or reply on Instagram for you. Most apps also ask you to approve each change before it happens, so read what the assistant is about to do.
To see or remove an app later, go to Account, then Connected apps, and click Disconnect. If you own a team workspace, you also see apps your teammates connected to it. A teammate's app can only do what their role allows.
You can still connect with an API key instead (see Use an API key instead).
Add it to Claude
- In Claude, go to Customize and then Connectors.
- Click Add, then Add custom connector.
- Type a name, such as "Linkdeck", and enter
https://your-linkdeck-address/mcpas the server URL. Leave authentication as it is. - Click Add, then Connect. Sign in to Linkdeck if asked, pick the profiles and access, and click approve.
To use it in a chat, click the + button, choose Connectors and make sure Linkdeck is switched on. On Team and Enterprise plans, an Owner adds custom connectors under Organization settings and then Connectors.
In Claude Code, run claude mcp add --transport http linkdeck https://your-linkdeck-address/mcp, then /mcp to sign in.
Add it to ChatGPT
- Go to chatgpt.com/plugins, select the + button, then Add custom MCP server.
- Type a name, such as "Linkdeck", and enter
https://your-linkdeck-address/mcpas the Server URL. - Choose OAuth for authentication, create it, and sign in to Linkdeck when asked.
If you don't see Add custom MCP server, your plan or workspace doesn't allow custom MCP servers yet. If you use a login link or a Google or email sign-in link and the app doesn't continue after you sign in, start the connection again from the app.
Use an API key instead
Apps that can't sign in can use an API key, which can do anything the REST API can do on every profile on your account. Create one as described in Create an API key, named after the app.
- In a header (safest):
https://your-linkdeck-address/mcpwithAuthorization: Bearer ld_your_key. - In the address, for apps that can't send headers:
https://your-linkdeck-address/mcp/ld_your_key. Anyone with this address can use your key, so keep it private like a password.
Other AI apps
Any app that supports remote MCP servers over Streamable HTTP can connect at https://your-linkdeck-address/mcp, by signing in (OAuth 2.1 with PKCE, client ID metadata documents or dynamic registration) or with an API key. The server supports MCP versions 2026-07-28, 2025-11-25, 2025-06-18 and 2025-03-26.
What the assistant can do
| Tool | What it does |
|---|---|
list_profiles |
List your profiles and their IDs |
get_profile |
Read a profile with its tabs and blocks, in page order |
update_profile |
Change the name, bio, profile picture, social icons, username, theme, settings or whether the page is published |
add_block |
Add any block: a link (with a lock, a click goal or a sponsored label if you like), header, text, embed, image, mailing list signup, form, folder, FAQ, testimonial, divider, product card, messaging buttons, countdown, discount code, donate button, quote, timeline, resume, scrolling text, Shopify products, booking calendar, social icons, post grid or automatic feed |
update_block |
Change a block's content, look or schedule, hide or show it, or move it to another tab or folder |
delete_block |
Delete a block |
reorder_blocks |
Put the blocks in a new order |
get_analytics |
Views, visitors, clicks, scans, new subscribers and form replies, with top links, sources, places and devices. It can filter by country, city, device, browser, referrer or campaign, like the Analytics screen |
get_live_visitors |
Who's on your page in the last 30 minutes |
list_subscribers |
Your mailing list |
list_form_submissions |
Replies to your forms |
list_products |
Your products of every type, with views, sales and earnings |
create_product |
Add a draft download, course, coaching call, live event, membership or physical product |
update_product |
Change a product's details, price, checkout questions or stock, or publish or unpublish it |
list_orders |
Sales and free downloads, with booked times and shipping details |
mark_order_shipped |
Mark a physical order as sent, with a tracking link (the buyer gets an email) |
list_bookings |
Your coaching bookings |
list_discount_codes |
Your discount codes and how often they've been used |
create_discount_code |
Add a discount code |
set_discount_code_active |
Switch a discount code off or back on |
get_email_sync |
Which email service your list is connected to, if any |
list_email_broadcasts |
Your email broadcasts and how they did |
draft_email_broadcast |
Write or edit a draft email. It never sends: you review and send it from Audience, then Emails |
send_email_test |
Send a draft to your own email address |
list_email_flows |
Your automated email flows |
get_media_kit |
Your media kit |
list_planned_posts |
Posts in your social planner |
draft_social_post |
Add a draft to the planner. It never posts or schedules anything: you add photos and schedule it in Planner |
get_instagram_post_insights |
Reach, likes, comments, saves and shares on your recent Instagram posts |
list_short_links |
Your short links and their clicks |
create_short_link |
Make a short link |
get_short_link_stats |
Clicks on one short link by day, referrer, country and device |
list_qr_codes |
Your QR codes and their scans |
create_qr_code |
Make a new QR code |
The assistant can't send emails to your subscribers, schedule or publish social posts, reply to Instagram messages or comments, connect email, payment or social accounts, or delete products, profiles or pages. Do those in the dashboard. Everything else is in the REST API.
AI agents that look for skills can read a short guide to using Linkdeck safely, listed at your Linkdeck address followed by /.well-known/agent-skills/index.json. It tells them to ask you before publishing, sending or deleting anything.
The same rules apply as for the REST API: 30 requests per minute per key, and changes fail while editing is locked on your account. Changes to a published page are live straight away. Before asking for big changes, save a version of your page (click Versions in the editor), so you can go back if you don't like the result. See Versions and scheduled launches.
To disconnect an assistant, remove it in the app and revoke its key under API keys.
Webhooks
A webhook sends a message to an address you choose each time something happens on your page. Webhooks are set up per profile.
Events
| Event | Button in Settings | When it's sent |
|---|---|---|
subscriber.created |
New subscriber | Someone joins your mailing list |
form.submitted |
New form reply | Someone fills in a form block, or a contact form on one of your web pages |
link.broken |
A link breaks | A link on your page has failed two checks in a row, about a day apart |
order.paid |
A product sells | Someone pays for a product, or gets a free one |
Linkdeck checks every link on your published pages about once a day, including the addresses in smart link rules. Sites that block automated checks count as "couldn't check", not broken, so they don't send link.broken. Each broken link is reported once. Broken-link alerts aren't sent while editing is locked on your account.
Add a webhook
- Select the profile with the profile switcher.
- Go to Settings and find Webhooks.
- Paste the address that should receive events into Webhook address. It must start with
https://. - Click the events you want. New subscriber and New form reply are picked to start with.
- Click Add webhook.
- Copy the signing secret that appears. It's shown only once.
In Zapier, use Webhooks by Zapier with a Catch Hook trigger and paste its address. In Make, use a Custom webhook. Zapier and Make don't need the signing secret.
Each profile can have up to 10 webhooks. The list shows each one's address, its events, and when it last sent something and whether it was delivered.
Test a webhook
Click Send test next to a webhook. Linkdeck sends a ping event to the address. If it's received, you see "Test delivered". If not, you see an error with the HTTP status the address sent back.
What a webhook sends
Each event is a POST request with a JSON body:
{
"event": "subscriber.created",
"created_at": "2026-11-13T12:00:00.000Z",
"profile": { "id": "...", "username": "maya" },
"data": { "block_id": "...", "email": "fan@example.com", "name": "Sam", "subscribed_at": "2026-11-13T12:00:00.000Z" }
}
The data depends on the event:
subscriber.created:block_id,email,nameandsubscribed_at.form.submitted:block_id,form(the form's title),answers(keyed by field label) andsubmitted_at. Forms on web pages also includepage_id.link.broken:block_id,title,urlandproblem, a short description such as "Page not found (404)".order.paid:order_id,product_id,product(its name),amount(0 for free products),currency,email,nameandpaid_at.ping: amessageconfirming the test.
Every request also has these headers:
Linkdeck-Event: the event name.Linkdeck-Signature: a signature you can use to check the request came from Linkdeck.
Check the signature
If you run your own server, check the signature before trusting a request. The header looks like t=1763035200,v1=5f2b..., where:
tis the time the request was signed, in Unix seconds.v1is an HMAC-SHA256 of the textt, a dot, and the raw request body, made with your signing secret and written in hex.
To check it:
- Read
tandv1from the header. - Compute HMAC-SHA256 of
t+.+ the raw body, using your signing secret, as hex. - Compare your result with
v1. If they don't match, reject the request. - Reject requests where
tis more than 5 minutes old, so an old request can't be replayed.
Here's the same check in Node.js:
import crypto from "node:crypto";
function isFromLinkdeck(rawBody, signatureHeader, secret) {
const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const a = Buffer.from(expected, "hex");
const b = Buffer.from(parts.v1 || "", "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
Use the raw body exactly as received. If your framework parses the JSON first, the signature won't match.
Delivery and failures
- A delivery counts as successful when your address answers with a 2xx status within 10 seconds. Redirects aren't followed.
- Each event is sent once. Failed deliveries aren't retried, so make sure your address is reliable.
- After 20 failed deliveries in a row, the webhook switches itself off and shows "Switched off after 20 failed deliveries in a row." Fix the problem, then click Switch on.
To delete a webhook, click Remove next to it and confirm.
Related
Still stuck? Send us a message, or go back to all help topics.