---
title: "Linkbreakers QR code API with scan webhooks, SDKs and MCP"
description: "Create a tracked QR code with one API request and receive every scan on a signed webhook. SDKs for TypeScript, Python, Go, Java and Rust, and an MCP server for AI agents. Base URL, authentication, rate limits and examples."
canonical: "https://linkbreakers.com/developers"
---

# Linkbreakers QR code API with scan webhooks, SDKs and MCP

Linkbreakers is a REST API that generates a dynamic QR code for every link you create and sends each scan to your webhook. `POST https://api.linkbreakers.com/v1/links` with a `destination` creates the link, its short URL and its QR code, and `GET https://api.linkbreakers.com/v1/links/{id}?include=qrcodeSignedUrl` returns the QR code image URL. `POST https://api.linkbreakers.com/v1/webhooks` makes Linkbreakers POST every scan of that link to your endpoint as JSON, signed with HTTP Message Signatures (RFC 9421). Official SDKs: TypeScript, Python, Go, Java and Rust. AI agents can create and track QR codes through the hosted MCP server at `https://mcp.linkbreakers.com`. The Free plan costs $0, needs no credit card, and includes the REST API, webhooks and the MCP server.

How it compares with other QR code APIs: [What is the best QR code API for developers?](https://linkbreakers.com/help/article/best-qr-code-api-for-developers)

> REST API for links, QR codes, workflow steps, media (PDFs, images, videos), visitors, events, analytics, webhooks and custom domains. Bearer auth with a workspace API token.

## Base URL

`https://api.linkbreakers.com`

## Authentication

Send a workspace API token as `Authorization: Bearer <token>`. Create one yourself in the dashboard at https://app.linkbreakers.com/workspace/dashboard/api-tokens after a free signup at https://app.linkbreakers.com?offer=free-plan&ref=landing-free-plan&showcase=default; no sales contact is needed.

MCP clients sign in with OAuth 2.1 instead: the MCP server does not accept workspace API tokens. The full walkthrough for agents is [auth.md](https://linkbreakers.com/auth.md), and the protected resource metadata is at https://api.linkbreakers.com/.well-known/oauth-protected-resource.

## Rate limits

Every response describes where the caller stands in the IETF `RateLimit-Policy` and `RateLimit` header fields (draft-ietf-httpapi-ratelimit-headers), and in `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (a Unix timestamp) for clients that read those. A request past the limit gets `429 Too Many Requests` with `Retry-After` in seconds.

- Workspace API token: 720 requests per 60 seconds, per token.
- Dashboard session or OAuth token: 600 requests per 60 seconds, per token.
- No credentials: 300 requests per 60 seconds, per client IP.

Each plan also includes a number of API calls per billing cycle. Past it, calls answer `429` with the code `MAX_PUBLIC_API_QUERIED_REACHED` until the cycle renews or the plan changes.

## Example requests

List API scopes (no token needed):

```bash
curl https://api.linkbreakers.com/v1/api-scopes
```

List links:

```bash
curl "https://api.linkbreakers.com/v1/links?pageSize=5" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

Create a link with a tracked QR code:

```bash
curl -X POST https://api.linkbreakers.com/v1/links \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"destination": "https://example.com", "waitForQrcode": true}'
```

Get the link's QR code image URL (signed, it expires, so fetch it when you render):

```bash
curl "https://api.linkbreakers.com/v1/links/$LINK_ID?include=qrcodeSignedUrl" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

Send that link's scans to your endpoint with a webhook (linkId is the link's id; leave it out to receive every link's scans):

```bash
curl -X POST https://api.linkbreakers.com/v1/webhooks \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Scans", "endpointUrl": "https://hooks.example.com/linkbreakers", "linkId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"}'
```

## Scan webhooks

A webhook is created with `name` and `endpointUrl`, optionally a `linkId` to receive one link's scans only, and `triggers` to pick the workflow step kinds that fire it (`KIND_ENTRY`, `KIND_INTERACTION`, `KIND_EXIT`; empty means all). Each delivery is a JSON `POST` whose body carries:

- `type`: `event.completed` when a visit reaches its exit step (for a plain QR code, the redirect), `step.completed` for a matching step, with the step in `workflowStep`
- `event`: the scan, with `action` (`SCAN` or `CLICK`), `scannedAt`, `device` (type, browser, platform, country, city), `visitor` (email, phone and attributes once known), `traces` (what the visitor did at each step), `journey` and `link` (its `metadata` and `tags`)
- `lbid`: the Linkbreakers ID of the visit, for attribution in your own systems

Headers: `X-Linkbreakers-Event`, `X-Linkbreakers-Webhook-ID`, `X-Linkbreakers-Event-ID`, plus `Signature`, `Signature-Input`, `Signature-Agent` and `Content-Digest`, verifiable with public keys only ([how](https://linkbreakers.com/help/article/verify-webhook-signatures)). The full payload and delivery rules are in [How do webhooks work in Linkbreakers?](https://linkbreakers.com/help/article/how-do-webhooks-work-in-linkbreakers)

## Endpoints that need no authentication

- `GET https://api.linkbreakers.com/v1/api-scopes`: List API scopes
- `GET https://api.linkbreakers.com/v1/pricing/plans`: List pricing plans
- `GET https://api.linkbreakers.com/v1/public/page-theme-templates`: List page theme templates
- `GET https://api.linkbreakers.com/v1/public/qrcode-templates`: List QR code templates

## Bulk operations

- `POST https://api.linkbreakers.com/v1/links/batch`: Create multiple links in a single request
- `POST https://api.linkbreakers.com/v1/links/bulk`: Create multiple links in a single request
- `POST https://api.linkbreakers.com/v1/links/bulk/jobs`: Create links in bulk in the background

## Endpoints by resource

- [Agent Identity](https://linkbreakers.com/help/api/agent-identity) (2 endpoints): Claiming a workspace an AI agent registered for itself. An agent registers at the authorization server (https://mcp.linkbreakers.com/agent/identity, see https://linkbreakers.com/auth.md) and hands a person a claim link and a 6-digit code; these endpoints are the person's side of that ceremony.
- [Allowances](https://linkbreakers.com/help/api/allowances) (2 endpoints): What the workspace has used of each limit its plan sets, read from the same counters that enforce them.
- [Analytics Dashboard](https://linkbreakers.com/help/api/analytics-dashboard) (6 endpoints): Endpoints for managing analytics dashboards with flexible, config-driven widgets. Each widget defines its own data source and visualization.
- [Analytics Data](https://linkbreakers.com/help/api/analytics-data) (11 endpoints): Endpoints for retrieving aggregated analytics data for dashboard widgets including geographic breakdown, device distribution, and visitor trends.
- [API Scopes](https://linkbreakers.com/help/api/api-scopes) (1 endpoints): The permissions an API token or OAuth grant can hold. Every authenticated endpoint requires exactly one scope, declared on the operation.
- [Assistant](https://linkbreakers.com/help/api/assistant) (6 endpoints): Context-aware assistant that delegates to specialized sub-assistants based on the resource being edited.
- [Auth](https://linkbreakers.com/help/api/auth) (1 endpoints): Endpoints for handling authentication in Linkbreakers. These endpoints allow you to sign in, request password reset, and reset passwords.
- [Custom Domains](https://linkbreakers.com/help/api/custom-domains) (8 endpoints): Endpoints for managing custom domains in Linkbreakers. These endpoints allow you to register, verify, and manage custom domains for your workspace.
- [Directories](https://linkbreakers.com/help/api/directories) (5 endpoints): Endpoints for managing directories in Linkbreakers. Directories let you organize links and other directories into a hierarchical folder structure.
- [Events](https://linkbreakers.com/help/api/events) (2 endpoints): Endpoints for managing events in Linkbreakers. These endpoints allow you to collect data and list events.
- [Google Forms Integrations](https://linkbreakers.com/help/api/google-forms-integrations) (7 endpoints): Connect your Google account to automatically sync form responses from links that redirect to Google Forms.
- [Jobs](https://linkbreakers.com/help/api/jobs) (1 endpoints): Long-running operations. An endpoint that works in the background answers 202 Accepted with a job and a Location header; poll GET /v1/jobs/{id} until the status is JOB_STATUS_SUCCEEDED or JOB_STATUS_FAILED. Jobs can be read for 24 hours after they finish.
- [Link Settings](https://linkbreakers.com/help/api/link-settings) (4 endpoints): Endpoints for managing link-level data collection settings in Linkbreakers.
- [Links](https://linkbreakers.com/help/api/links) (14 endpoints): Endpoints for managing shortened links in Linkbreakers. These endpoints allow you to create, retrieve, list, and delete shortened links for your workspace.
- [Media](https://linkbreakers.com/help/api/media) (10 endpoints): Endpoints for managing media files in Linkbreakers. These endpoints allow you to upload, retrieve, list, and delete media files for your workspace.
- [Members](https://linkbreakers.com/help/api/members) (13 endpoints): Endpoints for managing members in Linkbreakers. These endpoints allow you to invite, retrieve, update, and delete members.
- [Page Theme Templates](https://linkbreakers.com/help/api/page-theme-templates) (11 endpoints): Endpoints for managing Page Theme Templates in Linkbreakers. These endpoints allow you to create, retrieve, update, publish, import, and delete reusable page styling.
- [Page Themes](https://linkbreakers.com/help/api/page-themes) (5 endpoints): Endpoints for managing page visual themes. These endpoints allow you to create, read, and update themes for canvas, cover, badge, container, typography, footer logo, and interactive elements.
- [Pricing](https://linkbreakers.com/help/api/pricing) (1 endpoints): Public pricing catalog: the plans, what each costs and what each allows. Prices come from the billing provider and limits from the code that enforces them.
- [QR Code Designs](https://linkbreakers.com/help/api/qr-code-designs) (5 endpoints): Endpoints for managing QR Code Designs in Linkbreakers. These endpoints allow you to create, retrieve, update, and delete QR Code Designs.
- [QR Code Templates](https://linkbreakers.com/help/api/qr-code-templates) (10 endpoints): Endpoints for managing QR Code Templates in Linkbreakers. These endpoints allow you to create, retrieve, update, and delete QR Code Templates.
- [Retargeting Pixels](https://linkbreakers.com/help/api/retargeting-pixels) (2 endpoints): Fire your ad platforms' retargeting pixels (Meta, Google, TikTok, LinkedIn, Google Tag Manager) when someone visits one of your links or scans one of your QR codes, so you can retarget them later.
- [Slack Integrations](https://linkbreakers.com/help/api/slack-integrations) (7 endpoints): Endpoints for managing the Slack integration. Connect your Slack workspace to receive real-time notifications when events occur on your links.
- [Tags](https://linkbreakers.com/help/api/tags) (2 endpoints): Endpoints for managing tags in Linkbreakers. These endpoints allow you to search for tags in a workspace.
- [Visitors](https://linkbreakers.com/help/api/visitors) (8 endpoints): Identify and manage visitors. Accepts system fields like $email, $phone and arbitrary key/value attributes.
- [Webhooks](https://linkbreakers.com/help/api/webhooks) (5 endpoints): Endpoints for managing webhooks in Linkbreakers. These endpoints allow you to create, list, and delete webhooks for event notifications.
- [Workflow Steps](https://linkbreakers.com/help/api/workflow-steps) (10 endpoints): Endpoints for managing workflow steps in Linkbreakers. Workflow steps define the behavior of links, such as redirection destinations and data collection flows.
- [Workspace Metrics](https://linkbreakers.com/help/api/workspace-metrics) (3 endpoints): Endpoints for analyzing workspace activity within Linkbreakers, covering rolling event totals, audience reach, and calendar heatmaps.
- [Workspace Tokens](https://linkbreakers.com/help/api/workspace-tokens) (5 endpoints): Endpoints for managing workspace tokens in Linkbreakers. These endpoints allow you to create, list, and delete workspace tokens for authentication.
- [Workspaces](https://linkbreakers.com/help/api/workspaces) (8 endpoints): Endpoints for managing workspaces in Linkbreakers. These endpoints allow you to update and get workspaces.

## Machine-readable descriptions

- [OpenAPI](https://linkbreakers.com/openapi.json) (upstream: https://api.linkbreakers.com/internal/openapi/api/v1/api.swagger.json)
- [API catalog](https://linkbreakers.com/.well-known/api-catalog) (RFC 9727)
- [API llms.txt](https://linkbreakers.com/api/llms.txt)
- [Agent view](https://linkbreakers.com/?mode=agent)

## SDKs

- TypeScript SDK: package `linkbreakers` on [npm](https://www.npmjs.com/package/linkbreakers), latest version [1.186.1](https://www.npmjs.com/package/linkbreakers/v/1.186.1), install with `npm install linkbreakers`, docs at https://linkbreakers.com/sdk/typescript, source at https://github.com/linkbreakers-com/linkbreakers-typescript
- Python SDK: package `linkbreakers` on [PyPI](https://pypi.org/project/linkbreakers/), latest version [1.186.1](https://pypi.org/project/linkbreakers/1.186.1/), install with `pip install linkbreakers`, docs at https://linkbreakers.com/sdk/python, source at https://github.com/linkbreakers-com/linkbreakers-python
- Go SDK: package `github.com/linkbreakers-com/linkbreakers-go` on [Go modules](https://pkg.go.dev/github.com/linkbreakers-com/linkbreakers-go), latest version [1.186.1](https://pkg.go.dev/github.com/linkbreakers-com/linkbreakers-go@v1.186.1), install with `go get github.com/linkbreakers-com/linkbreakers-go`, docs at https://linkbreakers.com/sdk/go, source at https://github.com/linkbreakers-com/linkbreakers-go
- Java SDK: package `com.linkbreakers:linkbreakers-sdk` on [Maven Central](https://central.sonatype.com/artifact/com.linkbreakers/linkbreakers-sdk), latest version [1.186.1](https://central.sonatype.com/artifact/com.linkbreakers/linkbreakers-sdk/1.186.1), install with `com.linkbreakers:linkbreakers-sdk`, docs at https://linkbreakers.com/sdk/java, source at https://github.com/linkbreakers-com/linkbreakers-java
- Rust SDK: package `linkbreakers` on [crates.io](https://crates.io/crates/linkbreakers), latest version [1.186.1](https://crates.io/crates/linkbreakers/1.186.1), install with `cargo add linkbreakers`, docs at https://linkbreakers.com/sdk/rust, source at https://github.com/linkbreakers-com/linkbreakers-rust

## Examples

Runnable examples, one directory per task, in [linkbreakers-com/examples](https://github.com/linkbreakers-com/examples):

- [Bulk dynamic QR codes from a CSV (Python)](https://github.com/linkbreakers-com/examples/tree/main/bulk-dynamic-qr-codes-from-csv-python): one dynamic QR code and short link per CSV row with the Python SDK, SVG files out, scan counts back to a CSV.

## CLI

- Homebrew: `brew install linkbreakers-com/tap/linkbreakers` ([registry](https://github.com/linkbreakers-com/homebrew-tap))
- Install script (macOS, Linux): `curl -fsSL https://cli.linkbreakers.com/install.sh | bash`
- npm: `npm install -g linkbreakers-cli` ([registry](https://www.npmjs.com/package/linkbreakers-cli), latest [1.186.1](https://www.npmjs.com/package/linkbreakers-cli/v/1.186.1))
- Docs: https://linkbreakers.com/cli, source: https://github.com/linkbreakers-com/linkbreakers-cli, latest release [v1.186.1](https://github.com/linkbreakers-com/linkbreakers-cli/releases/tag/v1.186.1)

## MCP servers

- Linkbreakers MCP: `https://mcp.linkbreakers.com` (oauth2). Create links, QR codes, workflows and media, and read visitors and analytics in your workspace.
  Local stdio server: `npx -y linkbreakers-mcp` (package `linkbreakers-mcp` on [npm](https://www.npmjs.com/package/linkbreakers-mcp), latest [1.186.2](https://www.npmjs.com/package/linkbreakers-mcp/v/1.186.2), source at https://github.com/linkbreakers-com/linkbreakers-mcp)
  Linkbreakers MCP supports MCP Apps (`io.modelcontextprotocol/ui`, `text/html;profile=mcp-app`) and the OpenAI Apps SDK (`openai/outputTemplate`): tool results render as interactive UI in the conversation. Views: Link card (`ui://linkbreakers/link-card.html`, for `links_create`, `links_get`); Visitors (`ui://linkbreakers/visitors-card.html`, for `visitors_list`); Workspace metrics (`ui://linkbreakers/workspace-metrics.html`, for `metrics_workspace`). [MCP Apps guide](https://linkbreakers.com/help/article/mcp-apps-interactive-ui)
- Linkbreakers Docs MCP: `https://linkbreakers.com/mcp` (no sign-in). Search and read the Linkbreakers help center and developer docs. No sign-in required.

## Plans

The Free plan costs $0, needs no credit card, and includes the REST API, webhooks and the MCP server. Prices and limits are in [pricing.md](https://linkbreakers.com/pricing.md). Questions: support@linkbreakers.com.