---
title: "Add a share"
method: POST
path: "/user/shares"
tags: ["user APIs"]
---

# Add a share

`POST /user/shares`

Adds a new share. The share id will be auto-generated

## Request body

- Share
  - `id` string — auto-generated unique share identifier
  - `name` string
  - `description` string — optional description
  - `scope` 1 | 2 — Options: * `1` - read scope * `2` - write scope
  - `paths` string[] — paths to files or directories, for share scope write this array must contain exactly one directory. Paths will not be validated on save so you can also create them after creating the share
  - `username` string
  - `created_at` integer — creation time as unix timestamp in milliseconds
  - `updated_at` integer — last update time as unix timestamp in milliseconds
  - `last_use_at` integer — last use time as unix timestamp in milliseconds
  - `expires_at` integer — optional share expiration, as unix timestamp in milliseconds. 0 means no expiration
  - `password` string — optional password to protect the share. The special value "[**redacted**]" means that a password has been set, you can use this value if you want to preserve the current password when you update a share
  - `max_tokens` integer — maximum allowed access tokens. 0 means no limit
  - `used_tokens` integer
  - `allow_from` string[] — Limit the share availability to these IP/Mask. IP/Mask must be in CIDR notation as defined in RFC 4632 and RFC 4291, for example "192.0.2.0/24" or "2001:db8::/32". An empty list means no restrictions

## Response `201`

successful operation

- ApiResponse
  - `message` string — message, can be empty
  - `error` string — error description if any

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `500` — Internal Server Error
- `default` — Unexpected Error

---

[API](https://skmtc.net/kanton-bern/apis/sftpgo.md) · [All operations](https://skmtc.net/kanton-bern/apis/sftpgo/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kanton-bern/sftpgo/versions/d8d616a479b0/schema)