Files API

Upload files, share them through links and download them. Every request sends a token in the Authorization: Bearer header; see Get started with the API.

Upload a file

POST /api/file

Uploads one file in a single multipart request and creates its shared link. Put the link settings fields before the file part: fields after it are ignored. For large files, resumable uploads or several files behind one link, use Start an upload instead. Email recipients can’t be set here; add them afterwards with Update link settings.

Permission: Files: Upload and share (files:write)
Act for a user: accepts the Dew-Act-As header. Personal tokens work too.

Parameters

Name	In	Type	Description
`domain`	query	string	The domain for the shared link. It must be active and one you may use. Defaults to the domain you call the API on.

Request body

Text fields are read up to 1024 bytes each.

Content type multipart/form-data.

Field	Type	Description
`link_type`	string: `public`, `protected`, `private`, `onetime`	Who can open the shared link. See Update link settings. Default `"public"`.
`protection_method`	string: `password`, `sms`, `email`	Required when `link_type` is `protected`.
`password`	string	Password links: the password.
`auto_generate`	string: `true`	Password links: `true` generates a password instead. The response returns a generated password once, as `generated_password`.
`phone_number`	string	SMS links: the full international number, such as `+15551234567`.
`country_code`	string	SMS links: ISO 3166-1 alpha-2 country, such as `US`. Used for display only.
`allowlist_id`	string	Required for `private` links: an allowlist available on the domain.
`file` (required)	file	The file. Its part’s file name becomes the file’s name (at most 1020 bytes) and its part’s `Content-Type` the file’s type. Must be the last part.

Response 200

The file was uploaded.

data is FileUploadResult.

{
  "success": true,
  "data": {
    "id": "q7Rk2LmZ",
    "url": "https://files.example.com/f/q7Rk2LmZ",
    "formatted_text": "https://files.example.com/f/q7Rk2LmZ",
    "filename": "report.pdf",
    "filesize": 1048576,
    "expires_at": "2026-11-03T09:15:00Z"
  },
  "message": "Upload successful"
}

Errors

Status	When	Example message
400	The request is invalid; `message` says what to change.
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, the domain is not one you may use (`Not allowed to use this domain`), or the user’s account is unlicensed (`Unlicensed`).	“Not allowed to use this domain”
413	The file is larger than the domain allows.	“File too large”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Upload a file from the request body

PUT /api/file/{filename}

Uploads one file sent as the raw request body and creates its shared link. Link settings go in the query string. Set Content-Type to the file’s type; without it the file is stored as application/octet-stream. Email recipients can’t be set here; add them afterwards with Update link settings.

Permission: Files: Upload and share (files:write)
Act for a user: accepts the Dew-Act-As header. Personal tokens work too.

Parameters

Name	In	Type	Description
`filename` (required)	path	string	The file’s name, URL-encoded, at most 1020 bytes.
`domain`	query	string	The domain for the shared link. It must be active and one you may use. Defaults to the domain you call the API on.
`link_type`	query	string: `public`, `protected`, `private`, `onetime`	Who can open the shared link. See Update link settings. Default `"public"`.
`protection_method`	query	string: `password`, `sms`, `email`	Required when `link_type` is `protected`.
`password`	query	string	Password links: the password.
`auto_generate`	query	string: `true`	Password links: `true` generates a password instead. The response returns a generated password once, as `generated_password`.
`phone_number`	query	string	SMS links: the full international number, such as `+15551234567`.
`country_code`	query	string	SMS links: ISO 3166-1 alpha-2 country, such as `US`. Used for display only.
`allowlist_id`	query	string	Required for `private` links: an allowlist available on the domain.

Request body

The file’s bytes.

Content type application/octet-stream.

Response 200

The file was uploaded.

data is FileUploadResult.

{
  "success": true,
  "data": {
    "id": "q7Rk2LmZ",
    "url": "https://files.example.com/f/q7Rk2LmZ",
    "formatted_text": "https://files.example.com/f/q7Rk2LmZ",
    "filename": "report.pdf",
    "filesize": 1048576,
    "expires_at": "2026-11-03T09:15:00Z"
  },
  "message": "Upload successful"
}

Errors

Status	When	Example message
400	The request is invalid; `message` says what to change.
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, the domain is not one you may use (`Not allowed to use this domain`), or the user’s account is unlicensed (`Unlicensed`).	“Your account is unlicensed. Contact your administrator to restore upload access.”
413	The file is larger than the domain allows.	“File too large”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Delete a file

DELETE /api/file/{id}

Permanently deletes a file you own and its shared link. Files received through a file request are deleted from the request instead.

Permission: Files: Delete (files:delete)
Act for a user: accepts the Dew-Act-As header. Personal tokens work too.

Parameters

Name	In	Type	Description
`id` (required)	path	string	The file’s ID, as returned when it was uploaded or listed.

Response 200

The file was deleted.

data is Success.

{
  "success": true,
  "message": "File deleted"
}

Errors

Status	When	Example message
400	The request is invalid, or the file was received through a file request (manage it from the request instead).	“Files received through a request are managed from the request. Open it to share or delete them.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or the file belongs to someone else.	“You do not have permission to delete this file”
404	No such item, or not one this token can reach.
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Get a file

GET /api/file/{id}/info

Returns a file you own. A file that belongs to someone else, or whose link has expired, is not found.

Permission: Files: View and download (files:read)
Act for a user: accepts the Dew-Act-As header. Personal tokens work too.

Parameters

Name	In	Type	Description
`id` (required)	path	string	The file’s ID, as returned when it was uploaded or listed.

Response 200

The file.

data is FileInfo.

{
  "success": true,
  "data": {
    "id": "q7Rk2LmZ",
    "name": "report.pdf",
    "size": 1048576,
    "mime_type": "application/pdf",
    "owner_id": "6f1c2a9e-4b7d-4e2a-9c3f-1d8e5b7a2c40",
    "downloads": 3,
    "created_at": "2026-10-04T09:15:00.123456Z",
    "expires_at": "2026-11-03T09:15:00Z",
    "domain_hostname": "files.example.com"
  }
}

Errors

Status	When	Example message
400	The request is invalid; `message` says what to change.
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or may not reach this item.
404	No such item, or not one this token can reach.

Get link settings

GET /api/file/{id}/link-settings

Returns who can open a file’s shared link: its link type and, depending on the type, the phone number, allowlist, invited email addresses or whether a one-time link was used. Passwords are never returned.

Permission: Files: View and download (files:read)
Act for a user: accepts the Dew-Act-As header. Personal tokens work too.

Parameters

Name	In	Type	Description
`id` (required)	path	string	The file’s ID, as returned when it was uploaded or listed.

Response 200

The link settings.

data is LinkSettings.

{
  "success": true,
  "data": {
    "file_id": "q7Rk2LmZ",
    "link_type": "protected",
    "protection_method": "email",
    "email_recipients": [
      {
        "id": "er_3f9a1c7b2d4e6f80",
        "email": "anna@example.com",
        "invitation_sent_at": "2026-10-04T09:16:02Z",
        "invitation_failed": false
      },
      {
        "id": "er_8b2e4d6f0a1c3e57",
        "email": "bob@example.com",
        "invitation_failed": true
      }
    ],
    "email_message": "Here are the signed contracts."
  }
}

Errors

Status	When	Example message
400	The request is invalid; `message` says what to change.
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or the file belongs to someone else.	“You do not have permission to view this file’s settings”
404	No such item, or not one this token can reach.

Update link settings

PUT /api/file/{id}/link-settings

Changes who can open a file’s shared link. Send the full settings for the link type; link_type is required. New email recipients get an invitation email; switching to onetime makes a used link work again. People who already opened a protected link must unlock it again when its password, phone number or type changes.

Permission: Files: Upload and share (files:write)
Act for a user: accepts the Dew-Act-As header. Personal tokens work too.

Parameters

Name	In	Type	Description
`id` (required)	path	string	The file’s ID, as returned when it was uploaded or listed.

Request body

Content type application/json.

Field	Type	Description
`link_type` (required)	string: `public`, `protected`, `private`, `onetime`	`public`: anyone with the link. `protected`: needs a password, a code sent by SMS, or a code sent to an invited email address. `private`: only from IP addresses on an allowlist. `onetime`: works for one download. Left out, the link becomes `public`. Default `"public"`.
`protection_method`	string: `password`, `sms`, `email`	Required when `link_type` is `protected`.
`password`	string	Password links: the password. Leave out both `password` and `auto_generate` to keep the current password.
`auto_generate`	boolean	Password links: generate a password instead. The response returns a generated password once, as `generated_password`.
`phone_number`	string	SMS links: the full international number, such as `+15551234567`. Spaces, dashes and brackets are allowed.
`country_code`	string	SMS links: ISO 3166-1 alpha-2 country, such as `US`. Used for display only.
`allowlist_id`	string	Required for `private` links: an allowlist available on the file’s domain.
`email_recipients`	array of object	Email links: everyone who should have access. People already on the link keep it and get no new email; new addresses get an invitation; addresses you leave out lose access.
`email_message`	string	Email links: a message included in invitations sent by this change.

Response 200

The link settings were saved.

data fields:

Field	Type	Description
`generated_password`	string	The link’s password, when you asked Dew to generate one (`auto_generate` without a password). This is the only time it is returned.

{
  "success": true,
  "message": "Link settings updated"
}

Errors

Status	When	Example message
400	The settings are invalid (for example `Choose who can open the link.` when `link_type` is missing, `Password is required`, `Phone number is required`, `SMS protection is not available for this domain`, `Allowlist not available for this domain`, `Invalid email address: …`), or the file was received through a file request.	“Protection method is required for protected links”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or the file belongs to someone else.	“You do not have permission to modify this file’s settings”
404	No such item, or not one this token can reach.
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Resend invitations

POST /api/file/{id}/resend-invitations

Emails the invitations of an email-protected link again. Each resent invitation carries a new link, so the one the person already has stops working; use failed_only=true to resend only invitations that couldn’t be sent. You can resend once every 30 seconds.

Permission: Files: Upload and share (files:write)
Act for a user: accepts the Dew-Act-As header. Personal tokens work too.

Parameters

Name	In	Type	Description
`id` (required)	path	string	The file’s ID, as returned when it was uploaded or listed.
`failed_only`	query	boolean	`true` resends only invitations that couldn’t be sent. Default `false`.

Response 200

The invitations are being sent.

data fields:

Field	Type	Description
`queued`	integer	How many invitations are being sent.

{
  "success": true,
  "data": {
    "queued": 2
  },
  "message": "Invitations resending"
}

Errors

Status	When	Example message
400	The link is not email-protected.	“This link is not email-protected”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or the file belongs to someone else.	“You do not have permission to manage this file”
404	No such item, or not one this token can reach.
429	Invitations were resent less than 30 seconds ago. Wait the number of seconds in `Retry-After`.	“Invitations were just resent. Please wait a moment before trying again.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Turn download receipts on or off

PUT /api/file/{id}/download-receipt

Turns on or off the email the owner gets the first time someone downloads the file through its shared link. The email is sent once; turn the receipt on again to get another. For a service account, the email goes to its contact address, and without one nothing is sent.

Permission: Files: Upload and share (files:write)
Act for a user: accepts the Dew-Act-As header. Personal tokens work too.

Parameters

Name	In	Type	Description
`id` (required)	path	string	The file’s ID, as returned when it was uploaded or listed.

Request body

Content type application/json.

Field	Type	Description
`enabled`	boolean	`true` turns the receipt on. Default `false`.

{
  "enabled": true
}

Response 200

The setting was saved.

data fields:

Field	Type	Description
`download_receipt`	boolean

{
  "success": true,
  "data": {
    "download_receipt": true
  },
  "message": "Download receipt updated"
}

Errors

Status	When	Example message
400	The body is not valid JSON, or email isn’t set up on the server.	“Email isn’t set up on this server, so download receipts can’t be sent.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or the file belongs to someone else.	“Not authorized”
404	No such item, or not one this token can reach.
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Change when a link expires

PUT /api/file/{id}/expiry

Sets when a file’s shared link expires. The date must be in the future and within the domain’s maximum link lifetime (max_expiry_at in List files). Only an admin signed in to the web app can remove the expiry with null, so API tokens always send a date.

Permission: Files: Upload and share (files:write)
Act for a user: accepts the Dew-Act-As header. Personal tokens work too.

Parameters

Name	In	Type	Description
`id` (required)	path	string	The file’s ID, as returned when it was uploaded or listed.

Request body

Content type application/json.

Field	Type	Description
`expires_at`	string (date-time)	The new expiry. `null` (no expiry) is refused under an API token.

{
  "expires_at": "2026-12-31T23:00:00Z"
}

Response 200

The expiry was saved.

data is Success.

{
  "success": true,
  "message": "Expiry date updated"
}

Errors

Status	When	Example message
400	The date is missing (`null`), in the past (`Expiry date must be in the future`) or beyond the domain’s maximum, the body is not valid JSON, or the file was received through a file request.	“Expiry date exceeds the maximum link lifetime for this domain”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or the file belongs to someone else.	“Not authorized”
404	No such item, or not one this token can reach.
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

List files

GET /api/files

Lists the files you own with their shared links, newest first by default, a page at a time. Files received through file requests are not listed. To get the next page, pass cursor_id and the cursor for your sort from the last file on the page; a page with fewer than limit files is the last.

Permission: Files: View and download (files:read)
Act for a user: accepts the Dew-Act-As header. Personal tokens work too.

Parameters

Name	In	Type	Description
`limit`	query	integer	Files per page. Values outside 1 to 100 return 15. Default `15`. Minimum 1. Maximum 100.
`search`	query	string	Only files whose name contains this text, ignoring case.
`sort`	query	string: `created_at`, `name`, `expires_at`	Sort field. Default `"created_at"`.
`order`	query	string: `asc`, `desc`	Sort direction for `name` (default `asc`) and `expires_at` (default `asc`, links that never expire last). `created_at` is always newest first.
`access_types`	query	string	Comma-separated link kinds to include: `public`, `password`, `sms`, `email`, `private`, `onetime`. Unknown values are ignored.
`cursor_id`	query	string	Next page: the `id` of the last file on the previous page, together with the cursor for the sort in use.
`cursor_ts`	query	string (date-time)	Next page when sorting by `created_at`: the last file’s `created_at`, unchanged.
`cursor_name`	query	string	Next page when sorting by `name`: the last file’s `name`.
`cursor_expires`	query	string (date-time)	Next page when sorting by `expires_at`: the last file’s `expires_at`, unchanged.
`cursor_expires_null`	query	string: `1`	Next page when sorting by `expires_at` and the last file never expires: `1`.

Response 200

A page of files.

data is array of FileListItem.

{
  "success": true,
  "data": [
    {
      "id": "q7Rk2LmZ",
      "name": "report.pdf",
      "size": 1048576,
      "url": "https://files.example.com/f/q7Rk2LmZ",
      "formatted_text": "https://files.example.com/f/q7Rk2LmZ",
      "downloads": 3,
      "created_at": "2026-10-04T09:15:00.123456Z",
      "expires_at": "2026-11-03T09:15:00Z",
      "max_expiry_at": "2027-10-04T09:15:00.123456Z",
      "link_type": "protected",
      "protection_method": "password",
      "domain_hostname": "files.example.com",
      "download_receipt": false
    }
  ]
}

Errors

Status	When	Example message
400	The request is invalid; `message` says what to change.
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or may not reach this item.
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Download a file

GET /api/file/{id}/download

Downloads a file you own, whatever its link settings, without counting as a download of its shared link. On storage that serves downloads directly, the answer is a redirect to a temporary storage URL; follow it. Range requests are supported for resuming.

Permission: Files: View and download (files:read)
Act for a user: accepts the Dew-Act-As header. Personal tokens work too.

Parameters

Name	In	Type	Description
`id` (required)	path	string	The file’s ID, as returned when it was uploaded or listed.

Response 200

The file’s bytes, with the file’s own content type.

Content type application/octet-stream.

Response 206

The requested byte range. A request for several ranges at once gets the whole file instead.

Content type application/octet-stream.

Response 302

Download from the URL in Location. It stays valid as long as the file takes to download at 1 MiB/s, at least 5 minutes and at most 24 hours.

Errors

Status	When	Example message
400	The request is invalid; `message` says what to change.
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or the file belongs to someone else.	“Not your file”
404	No such item, or not one this token can reach.
500	The file couldn’t be read from storage (`FILE_BLOB_MISSING` when it is gone, `FILE_READ` otherwise). Quote `ref` to your admin.	“Failed to retrieve file”

List files on your domains

GET /api/admin/files

Service account tokens only. Lists every user’s files on the service account’s domains, with their owners and shared links, a page at a time. Files received through file requests are not listed. Paging works as in List files.

Permission: Files: View and download (files:read)
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`limit`	query	integer	Files per page. Values outside 1 to 100 return 15. Default `15`. Minimum 1. Maximum 100.
`search`	query	string	Only files whose name contains this text, ignoring case.
`sort`	query	string: `created_at`, `name`, `expires_at`, `username`	Sort field. `username` sorts by the owner’s display name. Default `"created_at"`.
`order`	query	string: `asc`, `desc`	Sort direction for `name`, `expires_at` and `username` (default `asc`). `created_at` is always newest first.
`owner_ids`	query	string	Comma-separated user IDs: only their files.
`access_types`	query	string	Comma-separated link kinds to include: `public`, `password`, `sms`, `email`, `private`, `onetime`. Unknown values are ignored.
`cursor_id`	query	string	Next page: the `id` of the last file on the previous page, together with the cursor for the sort in use.
`cursor_ts`	query	string (date-time)	Next page when sorting by `created_at`: the last file’s `created_at`, unchanged.
`cursor_name`	query	string	Next page when sorting by `name`: the last file’s `name`.
`cursor_expires`	query	string (date-time)	Next page when sorting by `expires_at`: the last file’s `expires_at`, unchanged.
`cursor_expires_null`	query	string: `1`	Next page when sorting by `expires_at` and the last file never expires: `1`.
`cursor_username`	query	string	Next page when sorting by `username`: the last file’s `owner_username`.

Response 200

A page of files.

data is array of AdminFileListItem.

{
  "success": true,
  "data": [
    {
      "id": "q7Rk2LmZ",
      "name": "report.pdf",
      "size": 1048576,
      "url": "https://files.example.com/f/q7Rk2LmZ",
      "formatted_text": "https://files.example.com/f/q7Rk2LmZ",
      "downloads": 3,
      "created_at": "2026-10-04T09:15:00.123456Z",
      "expires_at": "2026-11-03T09:15:00Z",
      "max_expiry_at": "2027-10-04T09:15:00.123456Z",
      "link_type": "protected",
      "protection_method": "password",
      "domain_hostname": "files.example.com",
      "download_receipt": false,
      "owner_username": "Anna Berg",
      "owner_email": "anna@example.com"
    }
  ]
}

Errors

Status	When	Example message
400	`Dew-Act-As` was sent; it can’t be used here.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, is a personal token, or the request comes from an IP address outside the admin allowlist.	“Personal API tokens can’t be used for admin actions.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.