Creates a share from the request body.
Errors
401 when the instance requires an account to upload, 400 when a parameter
is unusable, 413 when the body exceeds the configured limit, 409 when no
unused code could be found.
tessera_session<token>Set by POST /auth/login. A browser sends it automatically; it is HttpOnly, so page scripts cannot read or set it.
kind?stringlink to make a share that redirects to the http or https URL in
the body. Omit for a file or a note, which the other parameters
distinguish.
filename?stringOriginal file name. Its presence is what makes this a file share rather than a note.
title?stringDisplay name, shown on the share page and in the link preview.
language?stringSyntax-highlighting hint for a text share.
expires_in_hours?integerHow long the share should last. Omit to use the instance's default.
int640 <= valueexpires_in_minutes?integerThe same in minutes, for a lifetime shorter than an hour. At least 1.
Send this or expires_in_hours, not both.
int640 <= valuemax_uses?integerHow many times it may be retrieved. Omit for unlimited; 1 is
burn-after-reading.
int320 <= valueencryption?stringlink or password to make an end-to-end encrypted share, whose body
arrives already sealed. See docs/encryption.md. Refused unless
/capabilities says encryption.
key_salt?stringFor encryption=password: the salt the password was stretched with, as
16 bytes of unpadded URL-safe base64. Handed to anyone who asks.
sealed_name?stringFor an encrypted file: its name and media type, sealed. Replaces
filename and, like it, makes this a file share.
sealed_details?stringFor an encrypted share: its title and a note's language, sealed.
Replaces title and language.
The content itself. Send the file as the raw body: no wrapper, no encoding.
body*ShareBodyapplication/octet-streamThe request body of POST /shares: the content itself, as bytes.
A named type only so the contract can say format: binary. Declaring the
body as Vec<u8> makes utoipa emit an array of integers, which a docs UI
renders as a JSON array editor and a generated client types as number[].
An empty body is refused with a 400, and that cannot be expressed here.
min_length is field-level, and the value_type above overrides the
field's schema; drop it and the body stops being binary. So the handler
enforces it, and a generator reading this will think an empty body is
valid.
binaryCreated
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 POST 'https://example.com/api/v1/shares?kind=link&filename=project.zip&title=Q3+report&language=typescript&expires_in_hours=24&expires_in_minutes=30&max_uses=3&encryption=link' \ -H 'Content-Type: application/octet-stream' \ -d 'string'{ "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}