# Links

Links are obscured, secure URLs to Onehub folders and files. They are created via unique tokens and are designed to provide shortcuts to Onehub content without requiring an account. You can **read** and **update** links.

## Read a Link

<mark style="color:blue;">`GET`</mark> `https://ws-api.onehub.com/:item/:item_id/link`

Retrieves the link object from an `:item` (folder or file) specified via `:item_id`.

#### Path Parameters

| Name      | Type    | Description                                                                 |
| --------- | ------- | --------------------------------------------------------------------------- |
| :item     | integer | The type of item. Can either be `folders` or `files`.                       |
| :item\_id | integer | The unique identifier of the item you would like to retrieve the link from. |

{% tabs %}
{% tab title="201 Returns the link object and a 201 if the call succeeds." %}

```yaml
{
  "content_item_link": {
    "token": "3mxsktkk",
    "token_accessible": false,
    "token_expires": false,
    "token_expires_at": null,
    "require_password": false,
    "role_id": null,
    "link": "/files/3mxsktkk",
    "url": "/files/849607/link"
  }
}
```

{% endtab %}
{% endtabs %}

## Update a Link

<mark style="color:orange;">`PUT`</mark> `https://ws-api.onehub.com/:item/:item_id/link`

Updates the link object on the `:item` (folder or file) specified via `:item_id`.

#### Path Parameters

| Name      | Type    | Description                                                             |
| --------- | ------- | ----------------------------------------------------------------------- |
| :item     | integer | The type of item. Can either be `folders` or `files`.                   |
| :item\_id | integer | The unique identifier of the item you would like to update the link on. |

#### Request Body

| Name              | Type    | Description                                                                                                               |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| require\_password | boolean | Should a password be required to access the link? Defaults to `false`.                                                    |
| password          | string  | Set the required password that must be entered before the link can be accessed. Required if `require_password` is `true`. |
| token\_accessible | boolean | Is the link enabled? Defaults to `false`.                                                                                 |

{% tabs %}
{% tab title="201 Returns the updated link object and a 201 if the call succeeds." %}

```yaml
{
  "content_item_link": {
    "token": "3mxsktkk",
    "token_accessible": true,
    "token_expires": false,
    "token_expires_at": null,
    "require_password": true,
    "role_id": null,
    "link": "/files/3mxsktkk",
    "url": "/files/849607/link"
  }
}
```

{% endtab %}
{% endtabs %}


---

# 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://developer.onehub.com/methods/links.md?ask=<question>
```

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.