Skip to content

Application links

Application links are the custom links shown in the shared header of Bizzkit products, before the links to the enabled Bizzkit products. They are the same links that users manage on the Links page in Bizzkit Start. For more information, see Managing custom links.

Any caller with a token that has the startapi/ scope can read, create, update, and delete application links. Changes apply to the header for all users in your organization.

Endpoints

Method Endpoint Responses
GET /api/application-links 200 OK with all application links, ordered by sortOrder.
GET /api/application-links/{id} 200 OK with the application link, or 404 Not Found if it doesn't exist.
POST /api/application-links 201 Created with the new application link and a Location header, or 400 Bad Request if the request isn't valid.
PUT /api/application-links/{id} 200 OK without a response body, 400 Bad Request if the request isn't valid, or 404 Not Found if the link doesn't exist.
DELETE /api/application-links/{id} 204 No Content, also when the link doesn't exist.

Fields

Field Type Description
id string The identifier of the link. Assigned by the API when the link is created.
displayName string Required. The text shown in the header. Must be between 1 and 25 characters.
url string Required. The address the link points to. Must be an absolute http or https URL.
target string How the link opens. Either NewTab or SameWindow. Defaults to NewTab.
sortOrder integer The position of the link among the custom links. Links are listed in ascending sortOrder.

When you create a link, the API assigns sortOrder automatically, so the new link is placed after all existing links. You can't set sortOrder when you create a link.

When you update a link, sortOrder is part of the request body. If you omit it, it's set to 0, which moves the link to the front of the custom links. To keep the link in its current position, send its current sortOrder value.

Validation errors

If the request body isn't valid, the API returns 400 Bad Request with one or more of the following messages:

Message Reason
Display name is required. displayName is missing or empty.
Display name must be at most 25 characters long. displayName is longer than 25 characters.
Url is required. url is missing or empty.
Url must be a valid URL. url isn't a valid URL.
Url must be an absolute http or https URL. url is a relative URL, or it doesn't use http or https.
Target must be a valid link target. target is a number that doesn't match an allowed value.

If target is a string other than NewTab or SameWindow, the request body can't be read, and the API returns a generic 400 Bad Request without these messages.

The following example creates a link that opens in a new tab. Replace ... with an access token that has the startapi/ scope.

1
2
3
4
curl -X POST https://startapi.bizzkit.biz/api/application-links `
-H "Authorization: Bearer ..." `
-H "Content-Type: application/json" `
-d '{ "displayName": "Wiki", "url": "https://wiki.example.com/", "target": "NewTab" }'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# authtoken defined and initialized previously
@api = https://startapi.bizzkit.biz

POST {{api}}/api/application-links HTTP/1.1
Authorization: Bearer {{authtoken}}
Content-Type: application/json

{
  "displayName": "Wiki",
  "url": "https://wiki.example.com/",
  "target": "NewTab"
}

Example response:

1
2
3
4
5
6
7
{
  "id": "3f2b8c1e-5d4a-4b7e-9c6f-1a2b3c4d5e6f",
  "displayName": "Wiki",
  "url": "https://wiki.example.com/",
  "sortOrder": 3,
  "target": "NewTab"
}

The following example changes the link to open in the same window and keeps its current position by sending the existing sortOrder.

1
2
3
4
curl -X PUT https://startapi.bizzkit.biz/api/application-links/3f2b8c1e-5d4a-4b7e-9c6f-1a2b3c4d5e6f `
-H "Authorization: Bearer ..." `
-H "Content-Type: application/json" `
-d '{ "displayName": "Wiki", "url": "https://wiki.example.com/", "target": "SameWindow", "sortOrder": 3 }'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# authtoken defined and initialized previously
@api = https://startapi.bizzkit.biz

PUT {{api}}/api/application-links/3f2b8c1e-5d4a-4b7e-9c6f-1a2b3c4d5e6f HTTP/1.1
Authorization: Bearer {{authtoken}}
Content-Type: application/json

{
  "displayName": "Wiki",
  "url": "https://wiki.example.com/",
  "target": "SameWindow",
  "sortOrder": 3
}

In the GET /api/navigation response, the application links come after the links to the enabled Bizzkit products, in ascending sortOrder. The shared header in the Bizzkit products shows the custom links first, in that same order, followed by the product links. Each application link is mapped to a navigation link as follows:

Application link Navigation link
displayName name
url url
target: NewTab target: _blank
target: SameWindow target: _self

See Getting started for an example response.

API reference

Use the full API reference when you need field-level details or response shapes.

Start API reference