Changes a share's settings after it exists.
Why this exists
Fixing everything at creation does not match how files get shared. The link goes out, then the meeting moves, the recipient asks for another day, or the wrong person was on the thread and the password must change now.
Who may
The same two as DELETE: the owning account, or the holder of the
management token an anonymous upload was given. The permission checked is
shares:delete: there is no shares:update, and requiring the right to
delete outright is the conservative choice.
Errors
400 for a value the instance will not accept, 404 when the caller has no
share with that code, which is also the answer for another account's share,
since telling them apart would confirm which codes exist. 410 when the
change would revive a share whose content the sweep already removed.
tessera_session<token>Set by POST /auth/login. A browser sends it automatically; it is HttpOnly, so page scripts cannot read or set it.
code*stringThe retrieval code. Normalised before lookup: O reads as 0, I and L read as 1, case is folded, spaces and hyphens are dropped, so 0ZPQ4M7K, ozpq-4m7k and OZPQ4M7K are the same share.
application/json- body
Body of PATCH /shares/{code}.
Every field is optional and omitting one leaves that setting alone. Sending
null clears it: absent and null are different instructions here.
The password travels in X-Share-Password, as everywhere else in this API,
because a header stays out of the query string, the access log and the
Referer. Only the instruction to remove it lives here, and that is not a
secret.
expires_in_hours?|How long from now the share should last. null means it stops expiring.
int640 <= valueexpires_in_minutes?|The same in minutes, for a lifetime shorter than an hour. At least 1;
null means it stops expiring. Send this or expires_in_hours, not
both.
int640 <= valuemax_uses?|How many more times it may be retrieved, counting from now. null means
unlimited.
Not a total: 1 on a share already retrieved three times allows one
more (the fourth), to whoever gets there first. The response's
uses_remaining echoes the same number.
int320 <= valueremove_password?booleanRemoves the share's password.
Setting one is X-Share-Password; this is the other direction. Sending
both is refused, not guessed at.
The share as it now stands
application/json- response
A share as the API describes it. Never carries the content.
code*stringThe retrieval code, as a person reads it.
copy_count*integerHow many times a client reported it being copied.
int320 <= valuecreated_at*stringWhen it was created, RFC 3339.
disabled*booleanWhether it has been switched off, by an operator or because the scanner
found a threat. A disabled share answers 404 to everyone else.
encryption?|link or password for an end-to-end encrypted share, null for one
the server can read.
expires_at?|When it stops being served, RFC 3339, or null to live until deleted.
files*array<>Every file this share holds. Empty for text and for a locked share.
has_password*booleanWhether a password must be presented to retrieve it.
id*stringStable identifier.
key_salt?|The salt a password-derived key was stretched with, for password.
kind*stringtext, file or link.
language?|Syntax-highlighting hint.
last_accessed_at?|When it was last retrieved, RFC 3339.
Answers the question people ask of their own share: has it been picked up yet?
management_token?|Token that lets an anonymous uploader delete this share.
Shown once, at creation, and only for an anonymous upload. Only its digest is stored. Without it, a mistaken anonymous upload could never be taken back.
path*stringWhere the share lives, relative to this instance's origin.
Relative by design. The server does not know what host it is reached through, and guessing wrong behind a reverse proxy produces broken links. The caller already knows the origin it called.
scan_detail?|The threat's name for infected; encrypted or too_large for
skipped.
scan_state?|The malware scanner's verdict, the most significant across its files:
pending, clean, infected, skipped or deferred. null when it
was never sent to a scanner. See docs/scanning.md.
scanning*booleanWhether it is waiting for the malware scanner. Until it is done,
downloads answer 423 with Retry-After.
sealed_details?|The title and a note's language, sealed, on an encrypted share.
size_bytes*integerSize of the content in bytes.
int640 <= valuetitle?|Display name.
use_count*integerHow many times it has been retrieved.
Counted by the server on the transfer path, so this is the number to trust. The two below are what a client reported.
int320 <= valueuses_remaining?|How many retrievals remain, or null for unlimited.
int320 <= valueview_count*integerHow many times a client reported showing it.
int320 <= valuecurl -X PATCH 'https://example.com/api/v1/shares/string' \ -H 'Content-Type: application/json' \ -d '{}'{ "code": "string", "copy_count": 0, "created_at": "string", "disabled": true, "encryption": "string", "expires_at": "string", "files": [ { "filename": "string", "position": 0, "sealed_name": "string", "size_bytes": 0 } ], "has_password": true, "id": "string", "key_salt": "string", "kind": "string", "language": "string", "last_accessed_at": "string", "management_token": "string", "path": "string", "scan_detail": "string", "scan_state": "string", "scanning": true, "sealed_details": "string", "size_bytes": 0, "title": "string", "use_count": 0, "uses_remaining": 0, "view_count": 0}