Attachments
Direct-to-object-storage file uploads and downloads.
Reserve a direct upload
/api/v1/attachment-uploadsAtomically reserves the declared byte count against the Workspace's pooled storage entitlement and returns a short-lived presigned URL bound to one method, one object key, and the reserved length. File bytes never pass through the Assign API.
The reservation expires if it is not completed. Expired, cancelled, and abandoned reservations release their quota.
Associating a completed attachment with a parent Task, comment, or Document is deliberately not part of this contract: attachment parent cardinality is an open decision and will be contracted with it rather than inferred from an implementation.
Header Parameters
Request Body
application/jsonstring <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 1·max 255Display filename, at most 255 UTF-8 bytes after NFC normalization.
It must not contain a path separator, null, or control character,
must not be . or .., and must not begin or end with whitespace or
a dot. A violating filename is rejected rather than rewritten.
Filenames never contribute to the server-generated object key.
integer·min 1·max 52428800Exact byte count to reserve. The free tier allows 50 MiB per object.
string·max 255Advisory only. The stored content type is detected from the object's leading bytes at completion and may differ.
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uri>Short-lived presigned URL bound to one method, one object key, and the reserved length. Treat it as a credential: never log it, store it, or share it.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Complete a reserved upload
/api/v1/attachment-uploads/{upload_id}/completeVerifies the uploaded object, streams it through the private malware scanner, and converts reserved bytes into stored bytes. Completion checks object existence, the exact observed size, the expected object key, and the SHA-256 digest, and decides the content type from the object's leading bytes — never from the client-declared type, which is advisory and is discarded.
Detection and the filename extension are independent grounds for
denial: an object whose detected type is on the execution-risk
denylist is rejected whatever it is named, and a denied extension is
rejected whatever the bytes contain. Neither can permit what the
other rejects. SVG is retained as a download-only attachment: it is
never eligible for inline display. Scanner failures fail completion
closed. A detected malicious attachment is retained only in private
quarantine with scan_state: quarantined; it cannot be linked,
previewed, or downloaded.
Path Parameters
Header Parameters
Request Body
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 1·max 255Display filename, at most 255 UTF-8 bytes after NFC normalization.
It must not contain a path separator, null, or control character,
must not be . or .., and must not begin or end with whitespace or
a dot. A violating filename is rejected rather than rewritten.
Filenames never contribute to the server-generated object key.
string·max 255Server-detected from the object's leading bytes, not client-declared.
stringMalware-scan state. New uploads are scanned synchronously before
they become usable: only clean attachments may be linked, previewed,
or downloaded. quarantined attachments remain private and unavailable.
not_scanned is retained only for legacy migration visibility.
not_scannedpendingcleanquarantinedstring <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Cancel a reserved upload
/api/v1/attachment-uploads/{upload_id}Releases the reservation and its quota. The operation is idempotent and succeeds for an already-cancelled or already-expired reservation.
Path Parameters
Header Parameters
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Path Parameters
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 1·max 255Display filename, at most 255 UTF-8 bytes after NFC normalization.
It must not contain a path separator, null, or control character,
must not be . or .., and must not begin or end with whitespace or
a dot. A violating filename is rejected rather than rewritten.
Filenames never contribute to the server-generated object key.
string·max 255Server-detected from the object's leading bytes, not client-declared.
stringMalware-scan state. New uploads are scanned synchronously before
they become usable: only clean attachments may be linked, previewed,
or downloaded. quarantined attachments remain private and unavailable.
not_scanned is retained only for legacy migration visibility.
not_scannedpendingcleanquarantinedstring <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Delete an attachment
/api/v1/attachments/{attachment_id}Soft-deletes the attachment. Stored bytes continue to count against the storage entitlement until the object is permanently purged at the end of the retention window; deletion is never triggered automatically by quota exhaustion.
Path Parameters
Header Parameters
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Authorize a direct download
/api/v1/attachments/{attachment_id}/downloadAuthorizes the caller against the attachment's Workspace at request time and mints a short-lived presigned download URL bound to one method and one object key. Possession of an attachment identifier or an expired URL never grants access.
The URL is minted per request and must never be stored in Document or
comment content, an event payload, a notification, or a webhook. The
object is served from a non-Assign origin with
Content-Disposition: attachment and X-Content-Type-Options: nosniff; attachments are never rendered inline in an Assign origin.
Only an attachment whose scan_state is clean can receive this
credential. This operation is POST because it mints a credential; it is not a
cacheable read.
Path Parameters
Header Parameters
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Authorize an inline attachment preview
/api/v1/attachments/{attachment_id}/previewAuthorizes the caller against the attachment's Workspace at request
time and mints a short-lived presigned URL for browser display. The
object is served from the cookie-less object-storage origin with an
inline disposition, X-Content-Type-Options: nosniff, and the
server-detected content type.
Only clean PNG, JPEG, GIF, WebP, AVIF, and PDF attachments are previewable. SVG and every other type remain download-only. The URL is a credential, is minted per request, and must never be stored in content, events, notifications, or webhooks.
This operation is POST because it mints a credential; it is not a
cacheable read.
Path Parameters
Header Parameters
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.