> For the complete documentation index, see [llms.txt](https://docs.api.intratool.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.api.intratool.de/api-reference/url-context.md).

# UrlContext

## Introduction

The URL Context API resolves URLs into canonical intratool links and contextual metadata. Resources that support this API identify the [URL Context capability](/introduction/resource-capabilities/url-context.md) in their Model Definition.

Every requested URL produces one response item in the same position. The resolved context type and the authenticated user's access determine whether descriptive information is included.

When present, the `description` field uses the shared [Rich Text](/introduction/rich-text.md) HTML format.

## Response Structure

| Key                   | Type               | Presence                     | Description                                          |
| --------------------- | ------------------ | ---------------------------- | ---------------------------------------------------- |
| `key`                 | `string`           | Always                       | Original URL from the request.                       |
| `type`                | `string`           | Always                       | Resolved [context type](#context-types).             |
| `static_url`          | `string`           | Always                       | Canonical stable URL.                                |
| `url`                 | `string`           | Always                       | Current readable or content URL.                     |
| `provide_information` | `boolean`          | Always                       | Whether protected context information is included.   |
| `title`               | `string`           | When information is provided | Resolved display title.                              |
| `description`         | `string` \| `null` | When information is provided | Resolved HTML description.                           |
| `icon_name`           | `string` \| `null` | When information is provided | Resolved [Icon](/api-reference/icons.md) identifier. |
| `image_url`           | `string` \| `null` | When information is provided | Preview image URL.                                   |
| `data`                | `object` \| `null` | When information is provided | Type-specific metadata.                              |

When `provide_information` is `false`, `title`, `description`, `icon_name`, `image_url`, and `data` are omitted rather than returned as `null`.

## Context Types

**`generic`**

Represents a URL that does not resolve to an intratool route. It currently returns no descriptive information.

**`internal`**

Represents an intratool route without a linkable resource. Its `data.route` value contains the route name. The title and icon are included only when the user may access that route.

**`linkableEntity`**

Represents a linkable resource such as a [Form](/api-reference/forms/forms.md), [Infoboard Post](/api-reference/infoboard/infoboard-posts.md), or [User](/api-reference/users.md). When access is allowed, `data.type` contains the resource alias and `data.id` its ID.

**`fileContentEntity`**

Represents a file-content URL for a supported resource such as a [Filemanager File](/api-reference/filemanager/filemanager-files.md). When access is allowed, `data` includes `entity_type`, `entity_id`, `filename`, `extension`, `mime_type`, `size`, and `download_url`.

**`sharedItem`**

Represents a [Shared Item](/api-reference/shared-items.md). Information is available only when the Shared Item redirects and its access rules allow the user to reach the target. Its `data` identifies the Shared Item type and the target resource, including whether a soft-deletable target has been deleted.

## Resolve

Resolve one or more URLs.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/url-context`

**Request Keys**

| Key      | Type       | Default | Description                  |
| -------- | ---------- | ------- | ---------------------------- |
| `urls`\* | `string[]` | -       | One or more URLs to resolve. |

Keys with `*` are required.

**Behavior**

The response contains exactly one context for each submitted URL and preserves request order. Resolution does not grant access: module permissions, ownership, Targetables, Entity Permissions, and resource state can suppress protected information.

**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' => [
            '/files/4d835c85e4ad4e22b676c818',
            'https://www.intratool.de/'
        ]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "type": "fileContentEntity",
    "static_url": "/files/4d835c85e4ad4e22b676c818",
    "url": "/files/4d835c85e4ad4e22b676c818",
    "provide_information": true,
    "title": "annual-report.pdf",
    "description": "<strong>Size:</strong> 2 MB<br><strong>Modified:</strong> 08/05/2026 10:15 AM",
    "icon_name": "nc-single-folded-content",
    "image_url": null,
    "data": {
      "download_url": "/files/4d835c85e4ad4e22b676c818?download=true",
      "entity_type": "filemanagerFile",
      "entity_id": 86,
      "filename": "annual-report.pdf",
      "extension": "pdf",
      "mime_type": "application/pdf",
      "size": 2097152
    },
    "key": "/files/4d835c85e4ad4e22b676c818"
  },
  {
    "type": "generic",
    "static_url": "https://www.intratool.de/",
    "url": "https://www.intratool.de/",
    "provide_information": false,
    "key": "https://www.intratool.de/"
  }
]
```