UrlContext

Introduction

The UrlContext API allows the user to get context information about any given URL.

This can be useful to determine wether a URL is related to an linkable entity or the user is allowed to access it.

Depending on the resolved type, context information are provided in a consistent structure.

Structure

The structure of each URL Context is exactly the same. Wether all information are present depends on the type.

Key	Type	Description
key *	string	The provided URL.
type *	string	The type of the URL Context.
static_url *	string	The resolved static (never changing) URL.
url *	string	The resolved URL.
provide_information*	boolean	Wether additional information are provided.
title	string	The resolved title.
description	string	The resolved description (HTML).
icon_name	string	The resolved Icon name.
image_url	string	The resolved preview image URL.
data	array	Additional context data based on type.

Keys with * are always present in the URL Context.

Types

generic

The context for a external URL.

We currently don't provide information for this context type but plan to get title, description and image_url from the Open Graph data of the website.

linkableEntity

The context for a linkable entity (e.g. Form) provides the "readable" URL for the entity. It also includes title, description, icon_name and image_url information for the entity when the user is allowed to view it.

sharedItem

The context for a SharedItem provides the "readable" URL based on the type of the SharedItem. Wether title, description, icon_name and image_url information are provided depends on the user being authorized to view the shared item.

Get

Get the URL Context for the desired urls.

Definition

POST /api/url-context

Request Keys

Key	Type	Default	Description
url *	array	-	The URLs to get the context for.

Example Request

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/url-context', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'urls' => [
            'https://www.intratool.de/',
            '/infoboard/eintrag/zn7m24owk63qolxryge8pj05',
            '/geteilte-inhalte/9ae0e631-37b4-4ef0-8a26-1526f329098a'
        ]
    ]
]);

Example Response

[
  {
    "type": "generic",
    "static_url": "https://www.intratool.de/",
    "url": "https://www.intratool.de/",
    "provide_information": false,
    "key": "https://www.intratool.de/"
  },
  {
    "type": "linkableEntity",
    "static_url": "/infoboard/eintrag/zn7m24owk63qolxryge8pj05",
    "url": "/infoboard/eintrag/zn7m24owk63qolxryge8pj05",
    "provide_information": true,
    "title": "Lorem ipsum dolor sit amet",
    "description": null,
    "icon_name": "nc-chat-round-content",
    "image_url": null,
    "data": {
      "type": "infoboardPost"
    },
    "key": "/infoboard/eintrag/zn7m24owk63qolxryge8pj05"
  },
  {
    "type": "sharedItem",
    "static_url": "/geteilte-inhalte/9ae0e631-37b4-4ef0-8a26-1526f329098a",
    "url": "/handbuch/lorem-ipsum/#lorem-ipsum-dolor-sit-amet-consectetur-adipiscing-elit",
    "provide_information": true,
    "title": "Lorem ipsum dolor sit amet, consectetur...",
    "description": "<p><strong>Erstellt von:</strong> intratool Admin</p><p><strong>Geändert:</strong> 01.01.2024 12:00</p><p></p><p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>",
    "icon_name": "nc-file-article",
    "image_url": null,
    "data": {
      "type": "manualEntry"
    },
    "key": "/geteilte-inhalte/9ae0e631-37b4-4ef0-8a26-1526f329098a"
  }
]