---
title: "Read or list files"
method: GET
path: "/v1/files"
tags: ["files"]
---

# Read or list files

`GET /v1/files`

Read the contents of files or list files from the remote system.

## Query parameters

- `action` 'list' | 'read', required
- `path` string, required
- `pattern` string
- `itself` 'false' | 'true'

## Response `200`

For "list": JSON array of file information.

For "read":  Multipart form data response with file contents and metadata. Raw multipart response example:

```
Content-Type: multipart/form-data; boundary=01234567890123456789012345678901\r
--01234567890123456789012345678901\r
Content-Disposition: form-data; name="files"; filename="/etc/hosts"\r
\r
127.0.0.1 localhost  # \xf0\x9f\x98\x80\nfoo\r\nbar\r
--01234567890123456789012345678901\r
Content-Disposition: form-data; name="response"\r
\r
{
    "result": [{"path": "/etc/hosts"}],
    "status": "OK",
    "status-code": 200,
    "type": "sync"
}\r
--01234567890123456789012345678901--\r
```

- ListFilesResponse
  - `type` string — Response type, "sync".
  - `status-code` integer — HTTP response status code.
  - `status` string — The description of the HTTP status code. See the [IANA list](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
  - `result` FileInfo[]
    - `path` string, required — Full path to the file or directory.
    - `name` string, required — Name of the file or directory.
    - `type` 'device' | 'directory' | 'file' | 'named-pipe' | 'socket' | 'symlink' | 'unknown', required — Type of file entry (e.g., "file", "directory", "symlink").
    - `size` integer — Size of the file in bytes (only for regular files).
    - `permissions` string, required — File permissions in octal format (for example, "644").
    - `last-modified` string, date-time, required — Last modified [time](#time) in RFC3339 format.
    - `user-id` integer — User ID of the owner.
    - `user` string — Username of the owner.
    - `group-id` integer — Group ID of the owner.
    - `group` string — Group name of the owner.

## Changes

> 12 revisions in range; 1 could not be searched.

- **2025-01-13** `20135041d803` — 2 breaking, 1 info
  - the `allOf[subschema #2]/result/items/group-id` response's property type/format changed from `integer`/`int32` to `integer`/`` for status `200` (media type: application/json)
  - the `allOf[subschema #2]/result/items/user-id` response's property type/format changed from `integer`/`int32` to `integer`/`` for status `200` (media type: application/json)
  - added `#/components/schemas/BaseResponse, subschema #2` to the `response` response property `allOf` list for the response status `200` (media type: multipart/form-data)
- **2025-01-02** `1cb37312be6c` — 1 info
  - endpoint added
- **2024-12-22** `b3903318c3bd` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/canonical/apis/pebble-api/changes/v1/files/get.md)

---

[API](https://skmtc.dev/canonical/apis/pebble-api.md) · [All operations](https://skmtc.dev/canonical/apis/pebble-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/canonical/pebble-api/revisions/a94f353eccac/schema)