# UrlContext
## Introduction
The `UrlContext` API allows the user to get context information about any given URL.
This can be useful to determine whether a URL is related to a linkable entity or whether the user is allowed to access it.
Depending on the resolved [type](#types), context information are provided in a consistent [structure](#structure).
## Structure
The structure of each URL Context is exactly the same. Whether all information is present depends on the [type](#types).
| Key | Type | Description |
| ----------------------- | ------- | -------------------------------------------------- |
| `key` \* | string | The provided URL. |
| `type` \* | string | The [type](#types) of the URL Context. |
| `static_url` \* | string | The resolved static (never changing) URL. |
| `url` \* | string | The resolved URL. |
| `provide_information`\* | boolean | Whether additional information is provided. |
| `title` | string | The resolved title. |
| `description` | string | The resolved description (HTML). |
| `icon_name` | string | The resolved [Icon](/api-reference/icons.md) name. |
| `image_url` | string | The resolved preview image URL. |
| `data` | array | Additional context data based on [type](#types). |
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.
### `internal`
The context for a internal URL (e.g. `/infoboard`) always provides the relative URL and allows to differentiate internal from external (`generic`) URLs. It also includes `title` and `icon_name` information for the URL when the user is allowed to view it.
### `linkableEntity`
The context for a linkable entity (e.g. [Form](/api-reference/forms/forms.md)) 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.
### `fileContentEntity`
The context for a file content entity (e.g. [FilemanagerFile](/api-reference/filemanager/filemanager-files.md)) provides the URL to show the file content of the entity. It also includes `title`, `description`, `icon_name` and `image_url` information for the entity when the user is allowed to view it. The `data` key also includes information about the `filename`, `extension`, `mime_type`, `size` and the `download_url` of the file.
### `sharedItem`
The context for a [SharedItem](/api-reference/shared-items.md) provides the "readable" URL based on the `type` of the `SharedItem`. Whether `title`, `description`, `icon_name` and `image_url` information are provided depends on the user being authorized to view the shared item.
## List
List the URL Context for the desired `urls`.
**Definition**
`POST` `/api/url-context`
**Request Keys**
| Key | Type | Default | Description |
| --------- | ----- | :-----: | -------------------------------- |
| `urls` \* | array | - | The URLs to get the context for. |
**Example Request**
{% tabs %}
{% tab title="PHP" %}
```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',
'/infoboard/eintrag/zn7m24owk63qolxryge8pj05',
'/files/doxjzrnmgklojd154qwp8602',
'/geteilte-inhalte/9ae0e631-37b4-4ef0-8a26-1526f329098a'
]
]
]);
```
{% endtab %}
{% endtabs %}
**Example Response**
```json
[
{
"type": "generic",
"static_url": "https://www.intratool.de/",
"url": "https://www.intratool.de/",
"provide_information": false,
"key": "https://www.intratool.de/"
},
{
"type": "internal",
"static_url": "/infoboard"",
"url": "/infoboard"",
"provide_information": true,
"title": "Infoboard",
"description": null,
"icon_name": "nc-chat-round-content",
"image_url": null,
"data": {
"route": "infoboard"
},
"key": "/infoboard"
},
{
"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",
"id": 20
},
"key": "/infoboard/eintrag/zn7m24owk63qolxryge8pj05"
},
{
"type": "fileContentEntity",
"static_url": "/files/doxjzrnmgklojd154qwp8602",
"url": "/files/doxjzrnmgklojd154qwp8602",
"provide_information": true,
"title": "Lorem-ipsum.jpg",
"description": "Größe: 150 KB
Geändert: 01.09.2024 12:00",
"icon_name": "nc-single-folded-content",
"image_url": "/files/doxjzrnmgklojd154qwp8602",
"data": {
"entity_type": "filemanagerFile",
"entity_id": 15,
"filename": "Lorem-ipsum.jpg",
"extension": "jpg",
"mime_type": "image/jpeg",
"size": 150000,
"download_url": "/files/doxjzrnmgklojd154qwp8602?download=true"
},
"key": "/files/doxjzrnmgklojd154qwp8602"
},
{
"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": "Erstellt von: intratool Service
Geändert: 01.01.2024 12:00
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
",
"icon_name": "nc-file-article",
"image_url": null,
"data": {
"type": "manualEntry",
"targetable_type": "manualEntry",
"targetable_id": 10,
"targetable_deleted": false
},
"key": "/geteilte-inhalte/9ae0e631-37b4-4ef0-8a26-1526f329098a"
}
]
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.api.intratool.de/api-reference/url-context.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.