Skip to content

Start a chunked attachment upload

POST
/attachment-uploads
curl --request POST \
--url https://api.engram.page/attachment-uploads \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "mime_type": "video/mp4", "mtime": 1709234567, "path": "videos/clip.mp4", "size_bytes": 52428800 }'

Opens a resumable upload for a file of size_bytes, refused up front with the same responses as POST /api/attachments (402 plan, size or quota, 415 executable extension, 422 invalid mime_type). The user’s other open sessions count against the quota at their declared sizes, at most 4 may be open (429 too_many_uploads), and a file over 10,000 parts is 402 file_too_large on every plan. Then PUT each part and complete. A storage backend without multipart support (self-host database storage) returns 501.

File to upload

Media typeapplication/json
AttachmentUploadStartRequest
object
mime_type

Detected from path if omitted.

string
nullable
mtime
number format: float
nullable
path
required
string

Example

videos/clip.mp4
size_bytes
required

Total file size.

integer
>= 1

Example

{
"mime_type": "video/mp4",
"mtime": 1709234567,
"path": "videos/clip.mp4",
"size_bytes": 52428800
}

Session opened

Media typeapplication/json
AttachmentUploadSession
object
part_count
required
integer
part_size
required
integer
upload_id
required
string format: uuid

Example

{
"part_size": 8388608
}

Attachments require a paid plan / quota

Media typeapplication/json
LimitError
object
current
integer
nullable
error
required
string
limit
One of:
integer
limit_key
string
nullable
reason
required
string
tier
string
nullable
upgrade_url
string
nullable

Example

{
"error": "limit_exceeded",
"limit_key": "vaults_cap",
"reason": "vaults_cap_exceeded",
"tier": "free"
}

Executable extension not allowed

Media typeapplication/json
MimeRejected
object
error
required
string
extension
required
string

Example

{
"error": "extension_not_allowed",
"extension": ".exe"
}

Missing size or path, or invalid mime_type

Media typeapplication/json
Error
object
errors
One of:
string

Example generated

{
"errors": {}
}

too_many_uploads: the user already holds the maximum open sessions (4); retry after retry-after seconds, once one completes or is aborted

Media typeapplication/json
Error
object
errors
One of:
string

Example generated

{
"errors": {}
}

Storage backend has no multipart support

Media typeapplication/json
MessageError
object
code

Stable machine-readable reason, where one is defined.

string
error
required
string

Example

{
"code": "blob_missing",
"error": "not found"
}

Storage backend failure

Media typeapplication/json
MessageError
object
code

Stable machine-readable reason, where one is defined.

string
error
required
string

Example

{
"code": "blob_missing",
"error": "not found"
}

rotation_in_progress: an encryption key rotation holds the account; retry after retry-after seconds.

Media typeapplication/json
MessageError
object
code

Stable machine-readable reason, where one is defined.

string
error
required
string

Example

{
"code": "blob_missing",
"error": "not found"
}