Opens a session.

POST

/api/v1/uploads

Errors

400 when Upload-Length is missing or unusable, 403 when the caller may not upload, 404 when code names no share, 507 when the declared length does not fit in what is left. The body says whose ceiling ran out.

Authorization

cookietessera_session<token>

Set by POST /auth/login. A browser sends it automatically; it is HttpOnly, so page scripts cannot read or set it.

Query Parameters

filename?string

What to call the file.

code?string

Retrieval code of the share to append to.

Omit to make a new share when the upload finishes.

encryption?string

link or password for a new end-to-end encrypted share. An upload into an existing share is sealed the way that share is, so this is refused alongside code. See POST /shares.

key_salt?string

For encryption=password: the salt, as for POST /shares.

sealed_name?string

For a file in an encrypted share: its name and media type, sealed. Replaces filename.

Response Body

The session

application/json

response

A session that has just been opened.

direct*boolean

Whether parts may go straight to the store instead of through here.

When true, GET /uploads/{id}/parts/{number} hands out a URL to PUT each part to, and POST /uploads/{id}/complete finishes with the ETag each PUT returned. PATCH works either way.

Depends on where this upload was placed and whether the operator has marked that store browser-reachable, which is why it is here and not in the capabilities: an instance with an S3 bucket and a local directory answers differently per upload.

id*string

Identifier, and the last segment of the URL to continue at.

length*integer

How much was declared.

Formatint64

Range0 <= value

offset*integer

How much has arrived. Zero, here.

Formatint64

Range0 <= value

part_size*integer

How much to send per chunk, in bytes.

A chunk that is not the last is accepted only up to a multiple of this; the rest comes back as a lower offset and has to be re-sent. Sending exact multiples avoids that entirely.

Formatint64

Range0 <= value

token?|

Proof that a later request is the same uploader, for an anonymous one.

Store this. It is shown once, and without it the upload cannot be resumed after the page is closed, the situation resuming exists for. null when the uploader is signed in, since their credential already answers.

curl -X POST 'https://example.com/api/v1/uploads?filename=holiday.mp4&code=4GSVV6QT'

{  "direct": true,  "id": "string",  "length": 0,  "offset": 0,  "part_size": 0,  "token": "string"}