> For the complete documentation index, see [llms.txt](https://docs.getlynx.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.getlynx.io/clevver-api/public-methods/files.md).

# Files

## Get a list of unarchived files associated with your account.

<mark style="color:blue;">`GET`</mark> `https://clevver.org/api/files`

#### Query Parameters

| Name     | Type    | Description                                                        |
| -------- | ------- | ------------------------------------------------------------------ |
| archived | Boolean | When true returns archived files (default: false)                  |
| filter   | String  | When 'untagged' returns only untagged files. (default: no filter.) |
| tags     | String  | A comma delimited list of tags                                     |
| page     | Integer | The page number to retrieve                                        |

{% tabs %}
{% tab title="200: OK Paginated List of files" %}

```json
{
    "data": [
        {
            "id": "95668cc0-1695-46cb-9a15-db16944e6f98",
            "user_id": 1,
            "name": "Monthly Report Jan 2024",
            "filename": "somefile.pdf",
            "file_size": 58404,
            "url": "https://get.clevver.org/4354c6f90a49ca0e1884be4226c56750f078ee74db53109ac6e5807425fbf30a.pdf",
            "forever_url": "https://clvr.ly/4354c6f90a49ca0e1884be4226c56750.pdf",
            "thumb_url": "/uploads/digital_asset/file/95668cc0-1695-46cb-9a15-db16944e6f98/thumb_365233683_214917471203265_1617498711144221366_n.png",
            "cdn_url": "https://clvr.ly/4354c6f90a49ca0e1884be4226c56750",
            "txid": "1dc65cefbb656fb124c6beed75cbe4c0218f94966c6e524911b03740730ea7b0",
            "content_type": "application/pdf",
            "status": "cached",
            "archived": false,
            "preview_type": "pdf",
            "created_at": "2024-01-24T05:26:54.172Z",
            "updated_at": "2024-01-25T04:42:43.458Z",
            "tags": ["report", "january", "2024"]
        }
    ],
    "meta": {
        "tags": ["report", "january", "2024", "december", "november", "2023"],
        "tag_counts": {
            "report": 3,
            "january": 1,
            "2024": 1,
            "december": 1,
            "november": 1,
            "2023": 2
        }
    },
    "pagination": {
        "total_entries": 1,
        "total_pages": 1,
        "current_page": 1,
        "next_page": null,
        "previous_page": null,
        "per_page": 10
    }
}
```

{% endtab %}
{% endtabs %}

## Retrieve data about a specific file

<mark style="color:blue;">`GET`</mark> `https://clevver.org/api/files/{file_id}`

#### Path Parameters

| Name                                       | Type   | Description        |
| ------------------------------------------ | ------ | ------------------ |
| file\_id<mark style="color:red;">\*</mark> | String | The id of the file |

{% tabs %}
{% tab title="200: OK The file data" %}

```json
{
    "message": "File loaded",
    "status": "success",
    "data": {
        "id": "95668cc0-1695-46cb-9a15-db16944e6f98",
        "user_id": 1,
        "name": "Monthly Report Jan 2024",
        "filename": "somefile.pdf",
        "file_size": 58404,
        "url": "https://get.clevver.org/4354c6f90a49ca0e1884be4226c56750f078ee74db53109ac6e5807425fbf30a.pdf",
        "forever_url": "https://clvr.ly/4354c6f90a49ca0e1884be4226c56750.pdf",
        "thumb_url": "/uploads/digital_asset/file/95668cc0-1695-46cb-9a15-db16944e6f98/thumb_365233683_214917471203265_1617498711144221366_n.png",
        "cdn_url": "https://clvr.ly/4354c6f90a49ca0e1884be4226c56750",
        "txid": "1dc65cefbb656fb124c6beed75cbe4c0218f94966c6e524911b03740730ea7b0",
        "content_type": "application/pdf",
        "status": "cached",
        "archived": false,
        "preview_type": "pdf",
        "created_at": "2024-01-24T05:26:54.172Z",
        "updated_at": "2024-01-25T04:42:43.458Z",
        "tags": ["report", "january", "2024"]
    }
}
```

{% endtab %}

{% tab title="404: Not Found Error response" %}

```json
{
    "error": "File not found",
    "status": "error",
    "data": []
}
```

{% endtab %}
{% endtabs %}

## Update a file

<mark style="color:orange;">`PUT`</mark> `https://clevver.org/api/{file_id}`

#### Path Parameters

| Name                                       | Type   | Description                  |
| ------------------------------------------ | ------ | ---------------------------- |
| file\_id<mark style="color:red;">\*</mark> | String | The id of the file to update |

#### Query Parameters

| Name    | Type   | Description                   |
| ------- | ------ | ----------------------------- |
| tags\[] | String | An array of tags for the file |
| name    | String | The name (title) of the file  |

{% tabs %}
{% tab title="200: OK File was updated successfully" %}

```json
{
    "message": "File updated",
    "status": "success",
    "data": {
        "id": "95668cc0-1695-46cb-9a15-db16944e6f98",
        "user_id": 1,
        "name": "Monthly Financial Report Jan 2024",
        "filename": "somefile.pdf",
        "file_size": 58404,
        "url": "https://get.clevver.org/4354c6f90a49ca0e1884be4226c56750f078ee74db53109ac6e5807425fbf30a.pdf",
        "forever_url": "https://clvr.ly/4354c6f90a49ca0e1884be4226c56750.pdf",
        "thumb_url": "/uploads/digital_asset/file/95668cc0-1695-46cb-9a15-db16944e6f98/thumb_365233683_214917471203265_1617498711144221366_n.png",
        "cdn_url": "https://clvr.ly/4354c6f90a49ca0e1884be4226c56750",
        "txid": "1dc65cefbb656fb124c6beed75cbe4c0218f94966c6e524911b03740730ea7b0",
        "content_type": "application/pdf",
        "status": "cached",
        "archived": false,
        "preview_type": "pdf",
        "created_at": "2024-01-24T05:26:54.172Z",
        "updated_at": "2024-01-25T04:42:43.458Z",
        "tags": ["report", "january", "2024", "finance"]
    }
}
```

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}
{% endtabs %}

## Archive a file

<mark style="color:purple;">`PATCH`</mark> `https://clevver.org/apifiles/{file_id}/archive`

#### Path Parameters

| Name     | Type   | Description                   |
| -------- | ------ | ----------------------------- |
| file\_id | String | The id of the file to archive |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "message": "File archived",
    "status": "success",
    "data": {
        "id": "95668cc0-1695-46cb-9a15-db16944e6f98",
        "user_id": 1,
        "name": "Monthly Report Jan 2024",
        "filename": "somefile.pdf",
        "file_size": 58404,
        "url": "https://get.clevver.org/4354c6f90a49ca0e1884be4226c56750f078ee74db53109ac6e5807425fbf30a.pdf",
        "forever_url": "https://clvr.ly/4354c6f90a49ca0e1884be4226c56750.pdf",
        "thumb_url": "/uploads/digital_asset/file/95668cc0-1695-46cb-9a15-db16944e6f98/thumb_365233683_214917471203265_1617498711144221366_n.png",
        "cdn_url": "https://clvr.ly/4354c6f90a49ca0e1884be4226c56750",
        "txid": "1dc65cefbb656fb124c6beed75cbe4c0218f94966c6e524911b03740730ea7b0",
        "content_type": "application/pdf",
        "status": "cached",
        "archived": true,
        "preview_type": "pdf",
        "created_at": "2024-01-24T05:26:54.172Z",
        "updated_at": "2024-01-25T04:42:43.458Z",
        "tags": ["report", "january", "2024"]
    }
}
```

{% endtab %}
{% endtabs %}

## Unarchive a file

<mark style="color:purple;">`PATCH`</mark> `https://clevver.org/apifiles/{file_id}/unarchive`

#### Path Parameters

| Name     | Type   | Description                     |
| -------- | ------ | ------------------------------- |
| file\_id | String | The id of the file to unarchive |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "message": "File restored",
    "status": "success",
    "data": {
        "id": "95668cc0-1695-46cb-9a15-db16944e6f98",
        "user_id": 1,
        "name": "Monthly Report Jan 2024",
        "filename": "somefile.pdf",
        "file_size": 58404,
        "url": "https://get.clevver.org/4354c6f90a49ca0e1884be4226c56750f078ee74db53109ac6e5807425fbf30a.pdf",
        "forever_url": "https://clvr.ly/4354c6f90a49ca0e1884be4226c56750.pdf",
        "thumb_url": "/uploads/digital_asset/file/95668cc0-1695-46cb-9a15-db16944e6f98/thumb_365233683_214917471203265_1617498711144221366_n.png",
        "cdn_url": "https://clvr.ly/4354c6f90a49ca0e1884be4226c56750",
        "txid": "1dc65cefbb656fb124c6beed75cbe4c0218f94966c6e524911b03740730ea7b0",
        "content_type": "application/pdf",
        "status": "cached",
        "archived": false,
        "preview_type": "pdf",
        "created_at": "2024-01-24T05:26:54.172Z",
        "updated_at": "2024-01-25T04:42:43.458Z",
        "tags": ["report", "january", "2024"]
    }
}
```

{% endtab %}
{% endtabs %}