---
title: "Create, write, remove files/directories"
method: POST
path: "/v1/files"
tags: ["files"]
---

# Create, write, remove files/directories

`POST /v1/files`

This endpoint can:

- Write content to a path on the remote system. For this mode, use a multipart/form-data request body with JSON metadata in the first part. In the JSON metadata, set `action` to `write`.
- Create a directory or directory tree. For this mode, use an application/json request body with `action` set to `make-dirs`.
- Delete a file or directory. For this mode, use an application/json request body with `action` set to `remove`.

## Request body

- union
  - PostFilesMakeDirsRequest
    - `action` 'make-dirs', required
    - `dirs` MakeDirsItem[], required
      - `path` string, required — The directory path to create.
      - `make-parents` boolean — Whether to create parent directories as needed.
      - `permissions` string — Permissions for the created directory (octal format, e.g., "755").
      - `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.
  - PostFilesRemovePathsRequest
    - `action` 'remove', required
    - `paths` RemovePathsItem[], required
      - `path` string, required — The path to the file or directory to remove.
      - `recursive` boolean — Whether to remove recursively (for directories).

## Response `200`

Successful operation. The result in the response is a JSON array of the file result object containing path and (optional) errors.

- PostFilesResponse — JSON metadata about the file read operation.
  - `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` FileResult[]
    - `path` string
    - `error` ErrorResult
      - `message` string, required — Error message.
      - `kind` 'daemon-restart' | 'generic-file-error' | 'login-required' | 'no-default-services' | 'not-found' | 'permission-denied' | 'system-restart' — Type of error.
      - `value` object — Additional error information, if any.

## Changes

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

- **2025-01-13** `20135041d803` — 2 info
  - the `oneOf[#/components/schemas/PostFilesMakeDirsRequest]/dirs/items/group-id` request property type/format was generalized from `integer`/`int32` to `integer`/``
  - the `oneOf[#/components/schemas/PostFilesMakeDirsRequest]/dirs/items/user-id` request property type/format was generalized from `integer`/`int32` to `integer`/``
- **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/post.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)