> 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/shared-items.md).

# SharedItems

## Introduction

Shared Items provide stable URLs for supported resources. Each item selects a target through `targetable_type` and `targetable_id`; its `type`, `redirect_type`, and `config` control how that target is exposed.

When a Shared Item redirects with a grant token, the generated target URL can grant temporary access according to the item's Entity Permissions. A plain redirect only succeeds when the user can already access the target.

## Model Definition

**Alias**

`sharedItem`

**Capabilities**

* [Entity Permissions](/introduction/resource-capabilities/entity-permissions.md) - Direct `view` grants restrict who can open a Shared Item, while direct `administrate` grants restrict administration access.
* [URL Context](/introduction/resource-capabilities/url-context.md) - Resolves stable Shared Item URLs and exposes target context only when the redirect and access rules allow it.

**Relations**

| Key                 | Relation                                                  | Type       | Relation Field(s)                   |
| ------------------- | --------------------------------------------------------- | ---------- | ----------------------------------- |
| `user`              | [User](/api-reference/users.md)                           | Belongs to | `user_id`                           |
| `targetable`        | Target resource                                           | Morph to   | `targetable_type`, `targetable_id`  |
| `entityPermissions` | [EntityPermissions](/api-reference/entity-permissions.md) | Morph many | `target_entity`, `target_entity_id` |

**Types**

* `calendarEvent` - Shares a [Calendar Event](/api-reference/calendar/calendar-events.md) with an empty `config` object.
* `filemanagerDirectory` - Shares a [Filemanager Directory](/api-reference/filemanager/filemanager-directories.md) with type-specific configuration.
* `filemanagerFile` - Shares a [Filemanager File](/api-reference/filemanager/filemanager-files.md) with an empty `config` object.
* `form` - Shares a [Form](/api-reference/forms/forms.md) with an empty `config` object.
* `formMessage` - Shares a [Form Message](/api-reference/forms/form-messages.md) with an empty `config` object.
* `infoboardComment` - Shares an [Infoboard Comment](/api-reference/infoboard/infoboard-comments.md) with an empty `config` object.
* `infoboardPost` - Shares an [Infoboard Post](/api-reference/infoboard/infoboard-posts.md) with type-specific configuration.
* `manualChapter` - Shares a [Manual Chapter](/api-reference/manual/manual-chapters.md) with type-specific configuration.
* `manualEntry` - Shares a [Manual Entry](/api-reference/manual/manual-entries.md) with type-specific configuration.
* `taskExecution` - Shares a [Task Execution](/api-reference/tasks-2/task-executions.md) with an empty `config` object.

**Redirect Types**

* `none` - Does not redirect to the target.
* `redirect` - Redirects only when the user can already access the target.
* `redirectWithGrantToken` - Adds a grant token to the target URL when the user has `view` access to the Shared Item.

**Target URL Types**

The stable Shared Item URL accepts one of these boolean query parameters to select an alternate target URL:

* `showFileContent` - Uses the target's inline file-content URL when available.
* `downloadFileContent` - Uses the target's file-download URL when available.
* `filePoster` - Uses the target's poster-content URL when available.

## List

List Shared Items the authenticated user may view.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/shared-items`

**Request Keys**

| Key         | Type      | Default           | Description                                 |
| ----------- | --------- | ----------------- | ------------------------------------------- |
| `limit`     | `integer` | No limit          | Maximum number of Shared Items.             |
| `filter`    | `object`  | No filters        | Value filters applied before access checks. |
| `sort`      | `string`  | Repository order  | Sort expression.                            |
| `relations` | `string`  | Default relations | Pipe-separated relations to include.        |

**Behavior**

The list applies direct `view` Entity Permissions to restricted items and excludes soft-deleted items.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/shared-items', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'query' => [
        'limit' => 2
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "uuid": "7db2fe8a-c735-4a24-b73d-f2f6b662496a",
    "user_id": 17,
    "type": "manualEntry",
    "redirect_type": "redirectWithGrantToken",
    "targetable_type": "manualEntry",
    "targetable_id": 418,
    "config": {
      "show_subentries": true
    },
    "created_at": "2026-07-10 09:30:00",
    "updated_at": "2026-07-10 09:30:00",
    "deleted_at": null
  },
  {
    "uuid": "b3991ea9-801f-4f61-809c-e2725799ecfb",
    "user_id": 24,
    "type": "filemanagerDirectory",
    "redirect_type": "redirect",
    "targetable_type": "filemanagerDirectory",
    "targetable_id": 92,
    "config": {
      "show_subdirectories": false
    },
    "created_at": "2026-07-11 11:00:00",
    "updated_at": "2026-07-12 08:15:00",
    "deleted_at": null
  }
]
```

## Show

Show one Shared Item the authenticated user may view.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/shared-items/{sharedItem}`

**Route Parameters**

| Parameter    | Type     | Description       |
| ------------ | -------- | ----------------- |
| `sharedItem` | `string` | Shared Item UUID. |

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/shared-items/7db2fe8a-c735-4a24-b73d-f2f6b662496a', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "uuid": "7db2fe8a-c735-4a24-b73d-f2f6b662496a",
  "user_id": 17,
  "type": "manualEntry",
  "redirect_type": "redirectWithGrantToken",
  "targetable_type": "manualEntry",
  "targetable_id": 418,
  "config": {
    "show_subentries": true
  },
  "created_at": "2026-07-10 09:30:00",
  "updated_at": "2026-07-10 09:30:00",
  "deleted_at": null
}
```

## Admin: List

List Shared Items the authenticated user may administrate.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/shared-items`

**Request Keys**

| Key         | Type      | Default           | Description                                                |
| ----------- | --------- | ----------------- | ---------------------------------------------------------- |
| `limit`     | `integer` | No limit          | Maximum number of Shared Items.                            |
| `filter`    | `object`  | No filters        | Value filters applied before administration access checks. |
| `sort`      | `string`  | Repository order  | Sort expression.                                           |
| `relations` | `string`  | Default relations | Pipe-separated relations to include.                       |

**Behavior**

Users with global edit or delete access can administrate every item. Otherwise direct `administrate` Entity Permissions restrict items that carry grants; unrestricted items remain visible. This endpoint includes soft-deleted items.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/administration/shared-items', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'query' => [
        'limit' => 2
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "uuid": "b3991ea9-801f-4f61-809c-e2725799ecfb",
    "user_id": 24,
    "type": "filemanagerDirectory",
    "redirect_type": "redirect",
    "targetable_type": "filemanagerDirectory",
    "targetable_id": 92,
    "config": {
      "show_subdirectories": false
    },
    "created_at": "2026-07-11 11:00:00",
    "updated_at": "2026-07-12 08:15:00",
    "deleted_at": null
  },
  {
    "uuid": "49987c9e-bba3-40e9-b56f-e499c61562ec",
    "user_id": 31,
    "type": "infoboardPost",
    "redirect_type": "none",
    "targetable_type": "infoboardPost",
    "targetable_id": 735,
    "config": {
      "show_comments": false
    },
    "created_at": "2026-06-18 14:20:00",
    "updated_at": "2026-07-02 10:10:00",
    "deleted_at": "2026-07-02 10:10:00"
  }
]
```

## Admin: Show

Show one Shared Item the authenticated user may administrate.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/shared-items/{sharedItem}`

**Route Parameters**

| Parameter    | Type     | Description       |
| ------------ | -------- | ----------------- |
| `sharedItem` | `string` | Shared Item UUID. |

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/administration/shared-items/b3991ea9-801f-4f61-809c-e2725799ecfb', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "uuid": "b3991ea9-801f-4f61-809c-e2725799ecfb",
  "user_id": 24,
  "type": "filemanagerDirectory",
  "redirect_type": "redirect",
  "targetable_type": "filemanagerDirectory",
  "targetable_id": 92,
  "config": {
    "show_subdirectories": false
  },
  "created_at": "2026-07-11 11:00:00",
  "updated_at": "2026-07-12 08:15:00",
  "deleted_at": null
}
```

## Admin: Create

Create a Shared Item.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/administration/shared-items`

**Request Keys**

| Key                  | Type                  | Default          | Description                                                                               |
| -------------------- | --------------------- | ---------------- | ----------------------------------------------------------------------------------------- |
| `type`\*             | `string`              | -                | Selects one of the supported [Types](#types).                                             |
| `redirect_type`      | `string`              | Type default     | Selects one of the supported [Redirect Types](#redirect-types).                           |
| `targetable_type`\*  | `string`              | -                | Target resource alias allowed for `type`.                                                 |
| `targetable_id`\*    | `integer` \| `string` | -                | Existing target resource ID.                                                              |
| `config`             | `object`              | Type defaults    | Complete type-specific configuration.                                                     |
| `entity_permissions` | `object[]`            | No direct grants | Direct [Entity Permission](/api-reference/entity-permissions.md) grants for the new item. |

Keys with `*` are required.

**Behavior**

The authenticated user is stored as `user_id`. The target must match the selected type, and the user must be allowed to share that target. Omitted configuration is filled from the type defaults.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/administration/shared-items', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'type' => 'infoboardPost',
        'redirect_type' => 'redirectWithGrantToken',
        'targetable_type' => 'infoboardPost',
        'targetable_id' => 815,
        'config' => [
            'show_comments' => false
        ],
        'entity_permissions' => [
            [
                'key' => 'view',
                'permission_entity' => 'department',
                'permission_entity_id' => 8
            ]
        ]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "uuid": "424cff4c-6ef3-42c8-a9f1-ef6b534877c5",
    "user_id": 17,
    "type": "infoboardPost",
    "redirect_type": "redirectWithGrantToken",
    "targetable_type": "infoboardPost",
    "targetable_id": 815,
    "config": {
      "show_comments": false
    },
    "created_at": "2026-08-06 14:00:00",
    "updated_at": "2026-08-06 14:00:00",
    "deleted_at": null
  }
}
```

## Admin: Update

Update a Shared Item.

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/administration/shared-items/{sharedItem}`

**Route Parameters**

| Parameter    | Type     | Description       |
| ------------ | -------- | ----------------- |
| `sharedItem` | `string` | Shared Item UUID. |

**Request Keys**

| Key                  | Type                  | Description                                                            |
| -------------------- | --------------------- | ---------------------------------------------------------------------- |
| `redirect_type`      | `string`              | Updated redirect behavior.                                             |
| `targetable_type`    | `string`              | Updated target resource alias allowed for the item's immutable `type`. |
| `targetable_id`      | `integer` \| `string` | Updated existing target resource ID.                                   |
| `config`             | `object`              | Complete replacement type-specific configuration.                      |
| `entity_permissions` | `object[]`            | Complete replacement set of direct grants.                             |

**Behavior**

`user_id` and `type` cannot be changed. The existing configuration is preserved when `config` is omitted; when submitted, `config` replaces the stored object. When `entity_permissions` is submitted, direct grants are synchronized to the complete array.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/administration/shared-items/424cff4c-6ef3-42c8-a9f1-ef6b534877c5', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'redirect_type' => 'redirect',
        'targetable_type' => 'infoboardPost',
        'targetable_id' => 816,
        'config' => [
            'show_comments' => true
        ],
        'entity_permissions' => [
            [
                'key' => 'administrate',
                'permission_entity' => 'role',
                'permission_entity_id' => 14
            ]
        ]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "uuid": "424cff4c-6ef3-42c8-a9f1-ef6b534877c5",
    "user_id": 17,
    "type": "infoboardPost",
    "redirect_type": "redirect",
    "targetable_type": "infoboardPost",
    "targetable_id": 816,
    "config": {
      "show_comments": true
    },
    "created_at": "2026-08-06 14:00:00",
    "updated_at": "2026-08-06 14:30:00",
    "deleted_at": null
  }
}
```

## Admin: Delete

Soft-delete a Shared Item.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/administration/shared-items/{sharedItem}`

**Route Parameters**

| Parameter    | Type     | Description       |
| ------------ | -------- | ----------------- |
| `sharedItem` | `string` | Shared Item UUID. |

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('DELETE', '/api/administration/shared-items/424cff4c-6ef3-42c8-a9f1-ef6b534877c5', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": null
}
```