Links API Reference

#The Link object

Link represents a link in the system.

createdAt

string (date-time)

When the link was created.

customDomain

object

Represents a custom domain in the system

customDomainId

string

The ID of the custom domain. This is the custom domain that is used to access the link. If not defined, the link will be accessed using the default domain.

entrypoint

string

The entrypoint URL This is the URL that is available to be redirected to the destination.

eventCount

string (int64)

The number of time the link has been scanned. This number isn't refreshed instantly but will update itself within a few seconds.

fallbackDestination

string

leadGoalDefinition

string

The lead goal definition for the link. This is a text field that can be used to describe the lead goal or purpose of the link.

leadTargetDefinition

string

The lead target definition for the link. This is a text field that can be used to describe the target lead criteria for the link.

metadata

object

A map of string key-value pairs. All values must be strings. Nested objects or arrays are not supported. Maximum of 50 keys.

name

string

qrcodeDesign

object

qrcodeDesignId

string

The ID of the link design. This is the ID of the design that is used to generate the QR Code. If not defined, the design from the QR Code template will be used.

qrcodePendingUpdateSince

string (date-time)

When the link is pending QR Code update. This happens when the QR Code Design is updated and the QR Code image is still being processed.

qrcodeSignedUrl

string

The signed URL for the QR Code image. This URL eventually expires.

qrcodeTemplateId

string

The ID of the design template. This is the template that is used to generate the first QR Code Design assigned to the link. If not defined, a default QR Code Design will be generated.

shortlink

string

The short link for the link. This is the path segment that is attached to the URL. It can be defined by the client or generated by the system but is never null. It is unique within a custom domain or Linkbreakers default domain.

tags

array<object>

The tags associated with the link.

updatedAt

string (date-time)

When the link was last updated.

workspaceId

string

GET/v1/linksRequires auth

#List links

Retrieves the shortened links for your workspace

#Parameters

query parameters

pageSize

integer (int32)Requiredquery

The maximum number of links to return.

pageToken

stringquery

The token for retrieving the next page of results If not provided, the first page of results will be returned

include

array<string>query

List of related resources to include in the response.

tags

array<string>query

The tag to filter links by

stringquery

Search query to filter links by name or shortlink Search query to filter links by name or shortlink

#Response

200

Everything worked as expected.

links

array<object>

nextPageToken

string

#Error response

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

Example request (cURL)

curl -X GET "https://api.linkbreakers.com/v1/links?pageSize={pageSize}&pageToken={pageToken}&include={include}&tags={tags}&search={search}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Typical response

{
  "links": [
    {
      "createdAt": "2025-10-08T00:57:46.799Z",
      "customDomain": {
        "activatedAt": "2025-10-08T00:57:46.799Z",
        "createdAt": "2025-10-08T00:57:46.799Z",
        "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "lastCheckedAt": "2025-10-08T00:57:46.799Z",
        "name": "example.com",
        "status": "STATUS_UNSPECIFIED",
        "updatedAt": "2025-10-08T00:57:46.799Z",
        "workspaceId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
      },
      "customDomainId": "string",
      "entrypoint": "string",
      "eventCount": "string",
      "fallbackDestination": "string",
      "id": "string",
      "leadGoalDefinition": "string",
      "leadTargetDefinition": "string",
      "metadata": {},
      "name": "string",
      "qrcodeDesign": {
        "backgroundOptions": {},
        "centralImageSignedUrl": "string",
        "centralImageSize": 0,
        "cornersDotOptions": {},
        "cornersSquareOptions": {},
        "createdAt": "2025-10-08T00:57:46.799Z",
        "dotsOptions": {},
        "errorCorrectionLevel": "string",
        "height": 0,
        "hideBackgroundDots": false,
        "id": "string",
        "outputFileFormat": "OUTPUT_FILE_FORMAT_UNSPECIFIED",
        "shape": "SHAPE_UNSPECIFIED",
        "updatedAt": "2025-10-08T00:57:46.799Z",
        "width": 0
      },
      "qrcodeDesignId": "string",
      "qrcodePendingUpdateSince": "2025-10-08T00:57:46.799Z",
      "qrcodeSignedUrl": "string",
      "qrcodeTemplateId": "string",
      "shortlink": "string",
      "tags": [
        {}
      ],
      "updatedAt": "2025-10-08T00:57:46.799Z",
      "workspaceId": "string"
    }
  ],
  "nextPageToken": "string"
}

Base URL: https://api.linkbreakers.com

GET/v1/links/{id}Requires auth

#Get link details

Retrieves information about a shortened link including its metadata and metrics.

#Parameters

path parameters

stringRequiredpath

query parameters

include

array<string>query

List of related resources to include in the response.

#Response

200

Everything worked as expected.

link

object

Link represents a link in the system.

#Error response

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

Example request (cURL)

curl -X GET "https://api.linkbreakers.com/v1/links/{id}?include={include}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Typical response

{
  "link": {
    "createdAt": "2025-10-08T00:57:46.800Z",
    "customDomain": {
      "activatedAt": "2025-10-08T00:57:46.800Z",
      "createdAt": "2025-10-08T00:57:46.800Z",
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "lastCheckedAt": "2025-10-08T00:57:46.800Z",
      "name": "example.com",
      "status": "STATUS_UNSPECIFIED",
      "updatedAt": "2025-10-08T00:57:46.800Z",
      "workspaceId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
    },
    "customDomainId": "string",
    "entrypoint": "string",
    "eventCount": "string",
    "fallbackDestination": "string",
    "id": "string",
    "leadGoalDefinition": "string",
    "leadTargetDefinition": "string",
    "metadata": {},
    "name": "string",
    "qrcodeDesign": {
      "backgroundOptions": {
        "color": "string",
        "gradient": "string"
      },
      "centralImageSignedUrl": "string",
      "centralImageSize": 0,
      "cornersDotOptions": {
        "color": "string",
        "gradient": "string",
        "type": "string"
      },
      "cornersSquareOptions": {
        "color": "string",
        "gradient": "string",
        "type": "string"
      },
      "createdAt": "2025-10-08T00:57:46.800Z",
      "dotsOptions": {
        "color": "string",
        "gradient": "string",
        "type": "string"
      },
      "errorCorrectionLevel": "string",
      "height": 0,
      "hideBackgroundDots": false,
      "id": "string",
      "outputFileFormat": "OUTPUT_FILE_FORMAT_UNSPECIFIED",
      "shape": "SHAPE_UNSPECIFIED",
      "updatedAt": "2025-10-08T00:57:46.800Z",
      "width": 0
    },
    "qrcodeDesignId": "string",
    "qrcodePendingUpdateSince": "2025-10-08T00:57:46.800Z",
    "qrcodeSignedUrl": "string",
    "qrcodeTemplateId": "string",
    "shortlink": "string",
    "tags": [
      {
        "createdAt": "2025-10-08T00:57:46.800Z",
        "id": "string",
        "name": "string",
        "updatedAt": "2025-10-08T00:57:46.800Z"
      }
    ],
    "updatedAt": "2025-10-08T00:57:46.800Z",
    "workspaceId": "string"
  }
}

Base URL: https://api.linkbreakers.com

GET/v1/links/{linkId}/lead-score-explanation/{eventId}Requires auth

#Get lead score explanation

Generates an AI-powered explanation for a lead score result based on event data.

#Parameters

path parameters

linkId

stringRequiredpath

eventId

stringRequiredpath

#Response

200

Everything worked as expected.

breakdown

object

explanation

string

leadScore

integer (int32)

recurringScans

integer (int32)

#Error response

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

Example request (cURL)

curl -X GET "https://api.linkbreakers.com/v1/links/{linkId}/lead-score-explanation/{eventId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Typical response

{
  "breakdown": {
    "educationLevel": 0,
    "engagementQuality": 0,
    "professionalIntent": 0,
    "recurringInterest": 0,
    "technologicalAptitude": 0,
    "wealthIndicator": 0
  },
  "explanation": "string",
  "leadScore": 0,
  "recurringScans": 0
}

Base URL: https://api.linkbreakers.com

GET/v1/links/shortlink-availabilityRequires auth

#Check shortlink availability

Checks if a shortlink is available for use to create a new link. A custom domain can be provided to check against. It typically checks the shortlink slugs and shortlink IDs already present within the system.

#Parameters

query parameters

shortlink

stringquery

The shortlink to check availability for.

customDomainId

stringquery

The ID of the custom domain to check against If not provided, checks against the default domain

#Response

200

Everything worked as expected.

available

boolean

#Error response

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

Example request (cURL)

curl -X GET "https://api.linkbreakers.com/v1/links/shortlink-availability?shortlink={shortlink}&customDomainId={customDomainId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Typical response

{
  "available": false
}

Base URL: https://api.linkbreakers.com

GET/v1/links/shortlink-randomRequires auth

#Get a random shortlink

Generates a random availableshortlink for a new link.

#Parameters

This endpoint does not accept any parameters.

#Response

200

Everything worked as expected.

shortlink

string

#Error response

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

Example request (cURL)

curl -X GET "https://api.linkbreakers.com/v1/links/shortlink-random" \
  -H "Authorization: Bearer YOUR_TOKEN"

Typical response

{
  "shortlink": "string"
}

Base URL: https://api.linkbreakers.com

POST/v1/linksRequires auth

#Create a new link

This endpoint allows users to create a new shortened link in their Linkbreakers workspace. The URL will be checked for malicious content before being shortened.

#Parameters

This endpoint does not accept any parameters.

#Request body

customDomainId

string

destination

string

fallbackDestination

string

leadGoalDefinition

string

The lead goal definition for the link. This is a text field that can be used to describe the lead goal or purpose of the link.

leadTargetDefinition

string

The lead target definition for the link. This is a text field that can be used to describe the target lead criteria for the link.

metadata

object

A map of string key-value pairs. All values must be strings. Nested objects or arrays are not supported. Maximum of 50 keys.

name

string

qrcodeTemplateId

string

The ID of the QR Code template If not given, the default QR Code template will be used to generate the QR Code design.

shortlink

string

The shortlink for the link If not given, the shortlink will be generated by the system.

tags

array<string>

List of tags to associate with the link. If a tag doesn't exist, it will be created.

#Response

200

Everything worked as expected.

link

object

Link represents a link in the system.

#Error response

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

Example request (cURL)

curl -X POST "https://api.linkbreakers.com/v1/links" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"customDomainId":"string","destination":"https://example.com","fallbackDestination":"https://example.com/fallback","leadGoalDefinition":"Increase newsletter signups","leadTargetDefinition":"Marketing qualified leads with budget > $10k","metadata":{},"name":"My Link","qrcodeTemplateId":"string","shortlink":"my-link","tags":["string"]}'

Sample payload (application/json)

{
  "customDomainId": "string",
  "destination": "https://example.com",
  "fallbackDestination": "https://example.com/fallback",
  "leadGoalDefinition": "Increase newsletter signups",
  "leadTargetDefinition": "Marketing qualified leads with budget > $10k",
  "metadata": {},
  "name": "My Link",
  "qrcodeTemplateId": "string",
  "shortlink": "my-link",
  "tags": [
    "string"
  ]
}

Typical response

{
  "link": {
    "createdAt": "2025-10-08T00:57:46.799Z",
    "customDomain": {
      "activatedAt": "2025-10-08T00:57:46.799Z",
      "createdAt": "2025-10-08T00:57:46.799Z",
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "lastCheckedAt": "2025-10-08T00:57:46.799Z",
      "name": "example.com",
      "status": "STATUS_UNSPECIFIED",
      "updatedAt": "2025-10-08T00:57:46.799Z",
      "workspaceId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
    },
    "customDomainId": "string",
    "entrypoint": "string",
    "eventCount": "string",
    "fallbackDestination": "string",
    "id": "string",
    "leadGoalDefinition": "string",
    "leadTargetDefinition": "string",
    "metadata": {},
    "name": "string",
    "qrcodeDesign": {
      "backgroundOptions": {
        "color": "string",
        "gradient": "string"
      },
      "centralImageSignedUrl": "string",
      "centralImageSize": 0,
      "cornersDotOptions": {
        "color": "string",
        "gradient": "string",
        "type": "string"
      },
      "cornersSquareOptions": {
        "color": "string",
        "gradient": "string",
        "type": "string"
      },
      "createdAt": "2025-10-08T00:57:46.799Z",
      "dotsOptions": {
        "color": "string",
        "gradient": "string",
        "type": "string"
      },
      "errorCorrectionLevel": "string",
      "height": 0,
      "hideBackgroundDots": false,
      "id": "string",
      "outputFileFormat": "OUTPUT_FILE_FORMAT_UNSPECIFIED",
      "shape": "SHAPE_UNSPECIFIED",
      "updatedAt": "2025-10-08T00:57:46.799Z",
      "width": 0
    },
    "qrcodeDesignId": "string",
    "qrcodePendingUpdateSince": "2025-10-08T00:57:46.799Z",
    "qrcodeSignedUrl": "string",
    "qrcodeTemplateId": "string",
    "shortlink": "string",
    "tags": [
      {
        "createdAt": "2025-10-08T00:57:46.799Z",
        "id": "string",
        "name": "string",
        "updatedAt": "2025-10-08T00:57:46.799Z"
      }
    ],
    "updatedAt": "2025-10-08T00:57:46.799Z",
    "workspaceId": "string"
  }
}

Base URL: https://api.linkbreakers.com

PATCH/v1/links/{id}Requires auth

#Update a link

Updates an existing shortened link in your Linkbreakers workspace.

#Parameters

path parameters

stringRequiredpath

#Request body

fallbackDestination

string

leadGoalDefinition

string

The lead goal definition for the link. This is a text field that can be used to describe the lead goal or purpose of the link.

leadTargetDefinition

string

The lead target definition for the link. This is a text field that can be used to describe the target lead criteria for the link.

name

string

tags

array<string>

Set the tags to associate with the link. If a tag with the given name doesn't exist, it will be created.

tagsDelete

boolean

Delete all tags from the link If true, all tags will be removed from the link.

#Response

200

Everything worked as expected.

link

object

Link represents a link in the system.

#Error response

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

Example request (cURL)

curl -X PATCH "https://api.linkbreakers.com/v1/links/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"fallbackDestination":"https://example.com/fallback","leadGoalDefinition":"Increase newsletter signups","leadTargetDefinition":"Marketing qualified leads with budget > $10k","name":"My Updated Link","tags":["string"],"tagsDelete":false}'

Sample payload (application/json)

{
  "fallbackDestination": "https://example.com/fallback",
  "leadGoalDefinition": "Increase newsletter signups",
  "leadTargetDefinition": "Marketing qualified leads with budget > $10k",
  "name": "My Updated Link",
  "tags": [
    "string"
  ],
  "tagsDelete": false
}

Typical response

{
  "link": {
    "createdAt": "2025-10-08T00:57:46.800Z",
    "customDomain": {
      "activatedAt": "2025-10-08T00:57:46.800Z",
      "createdAt": "2025-10-08T00:57:46.800Z",
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "lastCheckedAt": "2025-10-08T00:57:46.800Z",
      "name": "example.com",
      "status": "STATUS_UNSPECIFIED",
      "updatedAt": "2025-10-08T00:57:46.800Z",
      "workspaceId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
    },
    "customDomainId": "string",
    "entrypoint": "string",
    "eventCount": "string",
    "fallbackDestination": "string",
    "id": "string",
    "leadGoalDefinition": "string",
    "leadTargetDefinition": "string",
    "metadata": {},
    "name": "string",
    "qrcodeDesign": {
      "backgroundOptions": {
        "color": "string",
        "gradient": "string"
      },
      "centralImageSignedUrl": "string",
      "centralImageSize": 0,
      "cornersDotOptions": {
        "color": "string",
        "gradient": "string",
        "type": "string"
      },
      "cornersSquareOptions": {
        "color": "string",
        "gradient": "string",
        "type": "string"
      },
      "createdAt": "2025-10-08T00:57:46.800Z",
      "dotsOptions": {
        "color": "string",
        "gradient": "string",
        "type": "string"
      },
      "errorCorrectionLevel": "string",
      "height": 0,
      "hideBackgroundDots": false,
      "id": "string",
      "outputFileFormat": "OUTPUT_FILE_FORMAT_UNSPECIFIED",
      "shape": "SHAPE_UNSPECIFIED",
      "updatedAt": "2025-10-08T00:57:46.800Z",
      "width": 0
    },
    "qrcodeDesignId": "string",
    "qrcodePendingUpdateSince": "2025-10-08T00:57:46.800Z",
    "qrcodeSignedUrl": "string",
    "qrcodeTemplateId": "string",
    "shortlink": "string",
    "tags": [
      {
        "createdAt": "2025-10-08T00:57:46.800Z",
        "id": "string",
        "name": "string",
        "updatedAt": "2025-10-08T00:57:46.800Z"
      }
    ],
    "updatedAt": "2025-10-08T00:57:46.800Z",
    "workspaceId": "string"
  }
}

Base URL: https://api.linkbreakers.com

PATCH/v1/links/{linkId}/lead-score-feedback/{eventId}Requires auth

#Update lead score feedback

Updates the feedback score and comment for a lead scoring analysis.

#Parameters

path parameters

linkId

stringRequiredpath

eventId

stringRequiredpath

#Request body

feedbackComment

string

feedbackScore

integer (int32)

Score from 0 to 10 rating the lead scoring accuracy

#Response

200

Everything worked as expected.

feedbackComment

string

feedbackScore

integer (int32)

success

boolean

#Error response

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

Example request (cURL)

curl -X PATCH "https://api.linkbreakers.com/v1/links/{linkId}/lead-score-feedback/{eventId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"feedbackComment":"Lead score seems accurate, good quality lead identified","feedbackScore":8}'

Sample payload (application/json)

{
  "feedbackComment": "Lead score seems accurate, good quality lead identified",
  "feedbackScore": 8
}

Typical response

{
  "feedbackComment": "string",
  "feedbackScore": 0,
  "success": false
}

Base URL: https://api.linkbreakers.com

DELETE/v1/links/{id}Requires auth

#Delete a link

Removes a shortened link from the workspace. This operation cannot be undone.

#Parameters

path parameters

stringRequiredpath

#Response

200

Everything worked as expected.

No structured schema available for this section.

#Error response

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.