Links

Links are the core part of Linkkit. Both short links and QR codes are covered under links section since the most common purpose of generating a QR code is to provide a portable way to access links. On this page, we'll dive into the different link endpoints you can use to manage links programmatically. We'll look at how to query, create, update, and delete links.

The link model

The link model contains all the information about your links. It also contains a reference to the statistics document that has information about the usage of a particular link.

Properties

Name
id
Type
string
Description
Unique identifier for the link.
Name
title
Type
string
Description
The title for the link. This is useful for identifying and searching for links.
Name
hostname
Type
string
Description
The hostname of the link. It will either be one of our default domains or a custom domain you have configured.
Name
path
Type
string
Description
The path of the link. This is the part of the link that comes after the hostname.
Name
destination
Type
string
Description
The destination URL for the link. This is where the link will redirect to when it is visited.
Name
createdAt
Type
string
Description
Timestamp of when the link was created.
Name
updatedAt
Type
timestamp
Description
Timestamp of when the link was last updated.
Name
ownerId
Type
timestamp
Description
The ID of the user or the organization that created the link.

GET/v1/links

List all links associated with your account

This endpoint allows you to retrieve a paginated list of all your links. By default, a maximum of ten links are shown per page.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of links returned. Defaults to 20.
Name
page
Type
integer
Description
The page number to return. Defaults to 1.
Name
query
Type
object
Description
Query for links by given parameters.
- Name
  hostname
  Type
  string
  Description
  Filter links by hostname. Exact matching.
- Name
  path
  Type
  string
  Description
  Filter links by path. Exact matching.
- Name
  destination
  Type
  string
  Description
  Filter links by destination. Exact matching.
- Name
  title
  Type
  string
  Description
  Filter links by title. Exact matching.

Request

GET

/v1/links

curl -G https://api.linkkit.chat/v1/links \
  -H "Authorization: Bearer {token}" \
  -d limit=10

Response

{
  "success": true,
  "data": [
    {
      "id": "WAz8eIbvDR60rouK",
      "destination": "https://linkkit.app",
      "hostname": "lkit.io",
      "path": "/opL",
      "createdAt": "2023-05-23T23:41:03.148Z",
      "updatedAt": "2023-05-23T23:41:03.148Z",
      "schemaVersion": "1.0",
      "ownerId": "u-hSIhXBhNe8X1d8Et"
    },
    {
      "id": "WAz8eIbvDR60rouK",
      // ...
    }
  ]
}

POST/v1/links

Create a link

This endpoint allows you to add a new link to your link list in Protocol. To add a link, you must provide their Protocol username and phone number.

Required attributes

Name
destination
Type
string
Description
The destination URL for the link. This is where the link will redirect to when it is visited.

Optional attributes

Name
hostname
Type
string
Description
The hostname of the link. It will either be one of our default domains or a custom domain you have configured. Current default is lkit.io.
Name
path
Type
string
Description
The path of the link. This is the part of the link that comes after the hostname. Includes the leading slash.
Name
title
Type
string
Description
The title for the link. This is useful for identifying and searching for links.

Request

POST

/v1/links

curl https://api.linkkit.app/v1/links \
  -H "Authorization: Bearer {token}" \
  -d hostname="custom.hostname.com" \
  -d path="/redirect" \
  -d destination="https://docs.linkkit.app/"

Response

{
  "success": true,
  "data": {
    "id": "WAz8eIbvDR60rouK",
    "destination": "https://linkkit.app",
    "hostname": "lkit.io",
    "path": "/opL",
    "createdAt": "2023-05-23T23:41:03.148Z",
    "updatedAt": "2023-05-23T23:41:03.148Z",
    "schemaVersion": "1.0",
    "ownerId": "u-hSIhXBhNe8X1d8Et"
  }
}

GET/v1/links/:id

Retrieve a link

This endpoint allows you to retrieve a link by providing their Protocol id. Refer to the list at the top of this page to see which properties are included with link objects.

Request

GET

/v1/links/WAz8eIbvDR60rouK

curl https://api.linkkit.app/v1/links/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "id": "WAz8eIbvDR60rouK",
    "destination": "https://linkkit.app",
    "hostname": "lkit.io",
    "path": "/opL",
    "createdAt": "2023-05-23T23:41:03.148Z",
    "updatedAt": "2023-05-23T23:41:03.148Z",
    "schemaVersion": "1.0",
    "ownerId": "u-hSIhXBhNe8X1d8Et"
  }
}

PUT/v1/links/:id

Update a link

This endpoint allows you to perform an update on a link. Currently, the only attribute that can be updated on links is the display_name attribute which controls how a link appears in your link list in Protocol.

Optional attributes

Name
display_name
Type
string
Description
The link display name in the link list. By default, this is just the username.

Request

PUT

/v1/links/WAz8eIbvDR60rouK

curl -X PUT https://api.linkkit.app/v1/links/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}" \
  -d path="/engage"

Response

{
  "success": true,
  "data": {
    "id": "WAz8eIbvDR60rouK",
    "username": "FrankMcCallister",
    "phone_number": "1-800-759-3000",
    "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg",
    "display_name": "UncleFrank",
    "conversation_id": "xgQQXg3hrtjh7AvZ",
    "last_active_at": 705103200,
    "created_at": 692233200
  }
}

DELETE/v1/links/:id

Delete a link

This endpoint allows you to delete links from your link list in Protocol. Note: This will also delete your conversation with the given link.

Request

DELETE

/v1/links/WAz8eIbvDR60rouK

curl -X DELETE https://api.linkkit.app/v1/links/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}"