Attachments API
Attachments and resumable (tus) uploads
GET /orgs/{org}/attachments
Lists attachments the caller can read, newest first.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
page | query | string | Only this page's attachments. |
entry | query | string | Only this entry's attachments. |
name | query | string | Only attachments with this file name (with page: resolves a name). |
trash | query | boolean | The trash instead. |
limit | query | integer (int64) | Page size (default 50, at most 200). |
cursor | query | string | next_cursor from the previous page. |
Responses
200- OK. Paged_AttachmentView
application/json
POST /orgs/{org}/attachments
Uploads a file (multipart, 32 MB or less; larger files use tus at /uploads). Fields: page, entry?, filename?, insert?, cursor? and file, in any order.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
Request body
multipart/form-data, UploadForm.
| Field | Type | Description |
|---|---|---|
cursor | integer (int64) | null | A byte offset in the page text to insert the reference at. |
entry | string | null | An entry on the page. |
file required | string (binary) | The file (32 MB or less), last. |
filename | string | null | The file name (default: the file part's name). |
insert | string | null | none, embed (default) or link. |
page required | string | The page (short ID or UUID). |
Responses
201- Created. AttachmentView
application/json 413- file_too_large or quota_exceeded
GET /orgs/{org}/attachments/{ref}
An attachment's metadata.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The attachment's short ID or UUID. |
Responses
200- OK. AttachmentView
application/json
PATCH /orgs/{org}/attachments/{ref}
Renames an attachment or moves it to another entry of its page.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The attachment's short ID or UUID. |
Request body
application/json, UpdateAttachment.
| Field | Type | Description |
|---|---|---|
entry | string | null | Move to this entry on the page (null detaches it from its entry). |
filename | string | null | A new file name (sanitised; (2) on a collision). References on the page follow unless update_references is false. |
update_references | boolean | null | Rewrite ![[old]] references on the page (default true). |
Responses
200- OK. AttachmentView
application/json
DELETE /orgs/{org}/attachments/{ref}
Moves an attachment to the trash (restorable for trash_days). References in the text stay, and render as "missing attachment".
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The attachment's short ID or UUID. |
Responses
200- OK. AttachmentView
application/json
PUT /orgs/{org}/attachments/{ref}/content
Uploads a new version (the raw body), keeping the short ID and name.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The attachment's short ID or UUID. |
Request body
application/octet-stream, integer (int32)[].
Responses
200- OK. AttachmentView
application/json
GET /orgs/{org}/attachments/{ref}/download
Redirects to a signed download URL (5 minutes). HTML and SVG always download as files; infected files can't be downloaded.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The attachment's short ID or UUID. |
Responses
302- to a signed /org/files URL
403- attachment_quarantined or humans_only
GET /orgs/{org}/attachments/{ref}/preview
Redirects to a WebP thumbnail (images, PDFs with a renderer, videos with ffmpeg), or 404 preview_not_available.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The attachment's short ID or UUID. |
size | query | integer (int32) | 256 (default) or 1024. |
Responses
302- to a signed WebP
404- preview_not_available
POST /orgs/{org}/attachments/{ref}/restore
Restores an attachment from the trash.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The attachment's short ID or UUID. |
Responses
200- OK. AttachmentView
application/json
GET /orgs/{org}/attachments/{ref}/text
The text extracted for search, paginated.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The attachment's short ID or UUID. |
offset | query | integer | The character offset (default 0). |
limit | query | integer | Characters per page (default 20000, at most 100000). |
Responses
200- OK. TextPage
application/json
GET /orgs/{org}/attachments/{ref}/versions
The kept versions, newest first (the current one first).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The attachment's short ID or UUID. |
Responses
200- OK. VersionView[]
application/json
POST /uploads
Resumable uploads (tus 1.0): create. Headers Tus-Resumable: 1.0.0, Upload-Length, Upload-Metadata (org, page, filename, and optionally entry, insert, cursor, base64 values). A body with Content-Type: application/offset+octet-stream is the first chunk.
Responses
201- created; Location names the upload
413- file_too_large or quota_exceeded
PATCH /uploads/{id}
Resumable uploads: appends a chunk at Upload-Offset. The last chunk creates the attachment, named in Aegent-Attachment.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | path | string (uuid) | The upload |
Request body
application/offset+octet-stream, integer (int32)[].
Responses
204- the new Upload-Offset
409- upload_offset_mismatch
DELETE /uploads/{id}
Resumable uploads: terminates an upload.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | path | string (uuid) | The upload |
Responses
204- No content