API

dosya.dev REST API

Everything you can do in the dashboard, you can do via the API. Upload terabytes, manage workspaces, and generate share links - all programmatically.

Get API Key View SDKs

Getting Started

Authentication

Base URL & API Key

# Base URL
https://api.dosya.dev/api

# All requests require an API key in the header
Authorization: Bearer dos_your-api-key

# Example: List your workspaces
$ curl https://api.dosya.dev/api/workspaces \
    -H "Authorization: Bearer dos_your-api-key"

Conventions

Response & error format

Every endpoint on this page follows the same envelope, so you can handle errors generically.

Error format

# Success responses
{ "ok": true, ... }

# Error responses - the HTTP status conveys the category (400, 401, 403, 404, 409, 429, ...)
{ "ok": false, "error": "<message>" }

# Some errors use a machine-readable string for "error" and spread in extra fields (e.g. an entity id)
{ "ok": false, "error": "folder_locked", "folder_id": "fld_2jd7m4qr", "lock_mode": "full_lock" }

Endpoints

API Reference

Click any endpoint to see its example request and response.

Files

POST /api/upload/init Initialize a file upload

{
  "file_name": "project-final.mp4",
  "file_size": 214748364800,
  "workspace_id": "ws_abc123",
  "mime_type": "video/mp4"
}

201 Created

{
  "ok": true,
  "session_id": "upl_7f3k9x2m",
  "upload_url": "/api/upload/upl_7f3k9x2m",
  "workspace_id": "ws_abc123",
  "file_name": "project-final.mp4",
  "file_size": 214748364800,
  "mime_type": "video/mp4",
  "extension": ".mp4",
  "region": "eu-central-2",
  "resumable": {
    "part_size": 10485760,
    "total_parts": 20480,
    "part_upload_url": "/api/upload/upl_7f3k9x2m/part",
    "complete_url": "/api/upload/upl_7f3k9x2m/complete",
    "status_url": "/api/upload/upl_7f3k9x2m/status"
  }
}

Note: for files at or under 50 MB, "resumable" is null - send the
whole body in a single PUT to upload_url (see the next endpoint).
Files over 50 MB use resumable multipart (10 MB parts): upload each
part to part_upload_url (idempotent - safe to retry), call
complete_url once every part has landed, and poll status_url to see
which parts made it through after a failure and resume from there.
There is no separate Idempotency-Key header: retry-safety comes from
per-part idempotency plus the resumable session itself. In-progress
sessions that see no activity for 10 minutes expire and must be
re-initiated.

curl -X POST https://api.dosya.dev/api/upload/init \
  -H "Authorization: Bearer dos_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "project-final.mp4",
    "file_size": 214748364800,
    "workspace_id": "ws_abc123",
    "mime_type": "video/mp4"
  }'

PUT /api/upload/:sessionId Upload the file body

Raw file bytes as the request body.

Headers:
  Content-Type: application/octet-stream

Stream the whole file as the PUT body - the server pipes it straight
to storage. (Files over 50 MB should instead use the resumable
multipart flow returned by /api/upload/init.)

201 Created

{
  "ok": true,
  "file": {
    "id": "file_8xk2m9p4",
    "name": "project-final.mp4",
    "r2_key": "ws_abc123/file_8xk2m9p4/project-final.mp4",
    "size_bytes": 214748364800,
    "mime_type": "video/mp4",
    "extension": ".mp4",
    "region": "eu-central-2",
    "version": 1,
    "created_at": 1745312400
  }
}

curl -X PUT https://api.dosya.dev/api/upload/upl_7f3k9x2m \
  -H "Authorization: Bearer dos_your-api-key" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @project-final.mp4

GET /api/files/:id Get file metadata

No request body required.

200 OK

{
  "ok": true,
  "file": {
    "id": "file_8xk2m9p4",
    "name": "project-final.mp4",
    "size_bytes": 214748364800,
    "mime_type": "video/mp4",
    "extension": ".mp4",
    "region": "eu-central-2",
    "uploaded_by": "usr_xk2m9p4n",
    "created_at": 1744626600,
    "updated_at": 1744626600,
    "deleted_at": null,
    "lock_mode": "none",
    "is_hidden": 0,
    "hidden_mode": "none",
    "current_version": 1,
    "workspace_id": "ws_abc123",
    "uploader_name": "Alice Chen",
    "share_count": 1,
    "comment_count": 0
  }
}

curl https://api.dosya.dev/api/files/file_8xk2m9p4 \
  -H "Authorization: Bearer dos_your-api-key"

GET /api/files/:id/download Download a file

No request body required.

Query parameters (optional):
  version=2    Download a specific version (default: current)
  ut=...       Unlock token, required for a full-locked file

302 Found

302 Found - this endpoint does NOT return a JSON body. It
redirects to a short-lived (5-minute) presigned URL that streams the
file straight from storage. Follow the redirect to download.

Location: https://<account>.r2.cloudflarestorage.com/...&X-Amz-Expires=300

# -L follows the redirect and writes the file to disk
curl -L https://api.dosya.dev/api/files/file_8xk2m9p4/download \
  -H "Authorization: Bearer dos_your-api-key" \
  -o project-final.mp4

DELETE /api/files/:id Delete a file

No request body required.

Note: the first DELETE soft-deletes the file to trash
("permanent": false). A second DELETE on an already-trashed file
permanently erases it and its versions ("permanent": true).

200 OK

{
  "ok": true,
  "permanent": false
}

curl -X DELETE https://api.dosya.dev/api/files/file_8xk2m9p4 \
  -H "Authorization: Bearer dos_your-api-key"

PUT /api/files/:id/rename Rename a file

{
  "name": "final-cut-v2.mp4"
}

200 OK

{
  "ok": true,
  "name": "final-cut-v2.mp4"
}

curl -X PUT https://api.dosya.dev/api/files/file_8xk2m9p4/rename \
  -H "Authorization: Bearer dos_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "final-cut-v2.mp4"
  }'

PUT /api/files/:id/move Move a file

{
  "folder_id": "fld_2jd7m4qr"
}

Note: pass "folder_id": null to move the file to the workspace root.

200 OK

{
  "ok": true
}

curl -X PUT https://api.dosya.dev/api/files/file_8xk2m9p4/move \
  -H "Authorization: Bearer dos_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_id": "fld_2jd7m4qr"
  }'

GET /api/files/:id/versions List file versions

No request body required.

200 OK

{
  "ok": true,
  "file_name": "project-final.mp4",
  "file_size": 214748364800,
  "file_mime": "video/mp4",
  "file_created": 1744453200,
  "current_version": 2,
  "versions": [
    {
      "id": "fver_9xk2m4p7",
      "version_number": 2,
      "size_bytes": 214748364800,
      "mime_type": "video/mp4",
      "extension": ".mp4",
      "uploaded_by": "usr_xk2m9p4n",
      "created_at": 1744626600,
      "uploader_name": "Alice Chen"
    },
    {
      "id": "fver_3kp7n2xm",
      "version_number": 1,
      "size_bytes": 198132736000,
      "mime_type": "video/mp4",
      "extension": ".mp4",
      "uploaded_by": "usr_xk2m9p4n",
      "created_at": 1744453200,
      "uploader_name": "Alice Chen"
    }
  ]
}

curl https://api.dosya.dev/api/files/file_8xk2m9p4/versions \
  -H "Authorization: Bearer dos_your-api-key"

Workspaces

POST /api/workspaces Create a workspace

{
  "name": "Marketing Assets",
  "default_region": "eu-central-2"
}

Note: "name" is the only required field. "default_region" is a label
- fetch valid codes from GET /api/regions - and defaults to
ap-southeast-2. Storage placement is effectively single-region per
workspace. You can also pass "icon_initials", "icon_color", and an
optional "max_total_storage_gb" cap.

201 Created

{
  "ok": true,
  "workspace": {
    "id": "ws_n4x8k2pm",
    "slug": "marketing-assets-n4x8k2",
    "name": "Marketing Assets",
    "icon_initials": "MA",
    "icon_color": "#22c55e"
  }
}

curl -X POST https://api.dosya.dev/api/workspaces \
  -H "Authorization: Bearer dos_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Assets",
    "default_region": "eu-central-2"
  }'

GET /api/workspaces List your workspaces

No request body required.

Note: returns the complete list of workspaces you belong to - no paging.

200 OK

{
  "ok": true,
  "workspaces": [
    {
      "id": "ws_abc123",
      "name": "Engineering",
      "slug": "engineering",
      "icon_initials": "EN",
      "icon_color": "#22c55e",
      "icon_image_url": null,
      "owner_id": "usr_xk2m9p4n",
      "default_region": "eu-central-2",
      "plan": "pro",
      "created_at": 1736499600,
      "storage_used_bytes": 536870912000,
      "role_id": "role_owner",
      "joined_at": 1736499600,
      "require_2fa": 0,
      "disable_password_login": 0,
      "storage": { "used": 536870912000, "total": 1099511627776 }
    }
  ],
  "allocation": { "...": "plan storage allocation summary" },
  "user_email": "you@example.com",
  "user_has_2fa": true,
  "user_login_method": "password"
}

curl https://api.dosya.dev/api/workspaces \
  -H "Authorization: Bearer dos_your-api-key"

GET /api/workspaces/:id Get workspace details

No request body required.

200 OK

{
  "ok": true,
  "workspace": {
    "id": "ws_abc123",
    "name": "Engineering",
    "slug": "engineering",
    "icon_initials": "EN",
    "icon_color": "#22c55e",
    "icon_image_url": null,
    "owner_id": "usr_xk2m9p4n",
    "default_region": "eu-central-2",
    "created_at": 1736499600,
    "storage_used_bytes": 536870912000
  },
  "settings": { "...": "per-workspace settings row (or null)" },
  "role_id": "role_owner",
  "is_owner": true,
  "plan": "pro",
  "storage": {
    "used": 536870912000,
    "total": 1099511627776,
    "free": 562640715776
  },
  "plan_limits": { "storage_gb": 1024 },
  "allocation": { "...": "plan storage allocation summary" }
}

curl https://api.dosya.dev/api/workspaces/ws_abc123 \
  -H "Authorization: Bearer dos_your-api-key"

GET /api/files List files in a workspace

Query parameters:
  workspace_id=ws_abc123   Required
  page=1            Page number (default 1)
  per_page=100      Results per page (default 100, clamped 10-500)
  sort=newest       newest (default), oldest, name_asc, name_desc, largest, smallest
  filter=all        all (default), documents, videos, images
  q=...             Search files by name
  folder_id=...     List a specific folder (omit for the workspace root)
  deleted=1         List trashed files instead of live ones
  hidden=1          List only hidden files (requires the hide-files permission)

200 OK

{
  "ok": true,
  "workspace_id": "ws_abc123",
  "folder_id": null,
  "folders": [
    {
      "id": "fld_2jd7m4qr",
      "name": "Videos",
      "file_count": 12,
      "total_size_bytes": 268435456000,
      "content_updated_at": 1744626600,
      "region": "eu-central-2",
      "created_at": 1744022400
    }
  ],
  "files": [
    {
      "id": "file_8xk2m9p4",
      "name": "project-final.mp4",
      "size_bytes": 214748364800,
      "mime_type": "video/mp4",
      "extension": ".mp4",
      "region": "eu-central-2",
      "current_version": 1,
      "created_at": 1744626600,
      "uploader_name": "Alice Chen",
      "share_count": 1,
      "comment_count": 0
    }
  ],
  "breadcrumbs": [],
  "pagination": {
    "page": 1,
    "per_page": 100,
    "total_files": 1,
    "total_pages": 1
  }
}

Note: pagination counts files only. The response also carries
can_lock, can_hide, and folder_view_only permission flags.

curl "https://api.dosya.dev/api/files?workspace_id=ws_abc123" \
  -H "Authorization: Bearer dos_your-api-key"

# Paging through results:
curl "https://api.dosya.dev/api/files?workspace_id=ws_abc123&page=2&per_page=100" \
  -H "Authorization: Bearer dos_your-api-key"

DELETE /api/workspaces/:id Delete a workspace

No request body required.

Note: you must first remove all other members, and you can't delete
your last workspace - either case returns 400.

200 OK

{
  "ok": true
}

curl -X DELETE https://api.dosya.dev/api/workspaces/ws_n4x8k2pm \
  -H "Authorization: Bearer dos_your-api-key"

Sharing

POST /api/files/:id/share Create a share link

{
  "expires_in_days": 30,
  "password": null,
  "lock_mode": "none"
}

201 Created

{
  "ok": true,
  "link": {
    "id": "sl_9xm2k4p7",
    "token": "9xm2k4p7wq3e5r7t9u1i2o",
    "url": "https://dosya.dev/s/9xm2k4p7wq3e5r7t9u1i2o",
    "lock_mode": "none",
    "expires_at": 1747908000,
    "created_at": 1745312400
  }
}

Note: "expires_in_days" is an integer number of days - omit it or pass
null for a link that never expires (if the workspace has a
share_max_expiry_days setting, longer values are capped to it).
"lock_mode" is one of none / view_only / full_lock; full_lock (and a
workspace force-password setting) requires "password" (min 8 chars).

curl -X POST https://api.dosya.dev/api/files/file_8xk2m9p4/share \
  -H "Authorization: Bearer dos_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_in_days": 30,
    "password": null,
    "lock_mode": "none"
  }'

GET /api/shares List active share links

Query parameters (required):
  workspace_id=ws_abc123

Note: workspace_id is required (omitting it returns 400). Returns at
most 100 links, most recent first - no further paging.

200 OK

{
  "ok": true,
  "links": [
    {
      "link_id": "sl_9xm2k4p7",
      "token": "9xm2k4p7wq3e5r7t9u1i2o",
      "file_id": "file_8xk2m9p4",
      "file_name": "project-final.mp4",
      "folder_id": null,
      "url": "https://dosya.dev/s/9xm2k4p7wq3e5r7t9u1i2o",
      "lock_mode": "none",
      "is_password_protected": 0,
      "view_count": 34,
      "download_count": 12,
      "is_revoked": 0,
      "expires_at": 1747908000,
      "shared_at": 1745312400,
      "status": "active",
      "is_folder": false,
      "display_name": "project-final.mp4",
      "is_mine": true
    }
  ],
  "stats": {
    "total": 1,
    "active": 1,
    "expiring": 0,
    "total_views": 34
  }
}

curl "https://api.dosya.dev/api/shares?workspace_id=ws_abc123" \
  -H "Authorization: Bearer dos_your-api-key"

POST /api/shares/:id/revoke Revoke a share link

No request body required.

Note: ":id" is the share link id (the "link_id" from the shares list).

200 OK

{
  "ok": true
}

curl -X POST https://api.dosya.dev/api/shares/sl_9xm2k4p7/revoke \
  -H "Authorization: Bearer dos_your-api-key"

Members

POST /api/team/invite Invite a member

{
  "email": "alice@example.com",
  "role": "role_member",
  "workspace_id": "ws_abc123"
}

Note: "role" is optional (defaults to role_member). It accepts a
built-in role id - role_admin, role_member, role_viewer - or a custom
workspace role id. role_owner cannot be assigned via invite.

201 Created

{
  "ok": true,
  "invite_id": "inv_4m8x2kp9"
}

curl -X POST https://api.dosya.dev/api/team/invite \
  -H "Authorization: Bearer dos_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "role": "role_member",
    "workspace_id": "ws_abc123"
  }'

GET /api/team List members

Query parameters (required):
  workspace_id=ws_abc123

Note: returns the complete member list for the workspace - no paging.

200 OK

{
  "ok": true,
  "workspace": {
    "name": "Engineering",
    "icon_initials": "EN",
    "icon_color": "#22c55e"
  },
  "members": [
    {
      "membership_id": "wm_xk2m9p4n",
      "user_id": "usr_xk2m9p4n",
      "role_id": "role_admin",
      "joined_at": 1739610000,
      "name": "Alice Chen",
      "email": "alice@example.com",
      "avatar_url": null,
      "last_active_at": 1745312400,
      "is_you": false
    }
  ],
  "invites": [
    {
      "id": "inv_4m8x2kp9",
      "email": "bob@example.com",
      "role_id": "role_member",
      "created_at": 1745312400,
      "expires_at": 1745917200,
      "invited_by_name": "Alice Chen",
      "invite_url": "https://dosya.dev/invite/…"
    }
  ],
  "activity": [
    {
      "id": "evt_9xk2m4p7",
      "action": "member_invited",
      "metadata": "{\"email\":\"bob@example.com\"}",
      "created_at": 1745312400,
      "user_name": "Alice Chen",
      "user_id": "usr_xk2m9p4n",
      "avatar_url": null,
      "meta": { "email": "bob@example.com" }
    }
  ],
  "stats": {
    "members": 1,
    "pending": 1,
    "shares_this_week": 4
  }
}

curl "https://api.dosya.dev/api/team?workspace_id=ws_abc123" \
  -H "Authorization: Bearer dos_your-api-key"

DELETE /api/team/members/:id Remove a member

No request body required.

Note: ":id" is the membership id (the "membership_id" from the members
list), not the user id.

200 OK

{
  "ok": true
}

curl -X DELETE https://api.dosya.dev/api/team/members/wm_7j3n8m2k \
  -H "Authorization: Bearer dos_your-api-key"

Webhooks

Get an HTTP callback the moment a file is uploaded, a file is deleted, or a share link is accessed - no polling required.

Registering an endpoint

Add a webhook from your workspace's Webhooks integration page, or register one directly with POST /api/webhooks (see below). The signing secret is returned once, on creation - store it right away, since it can't be fetched again later (only rotated via roll-secret).

Webhooks management API

POST /api/webhooks Register a webhook endpoint

{
  "workspace_id": "ws_abc123",
  "url": "https://example.com/hooks/dosya",
  "events": ["file.uploaded", "file.deleted", "share.accessed"],
  "description": "Slack notifier"
}

201 Created

{
  "ok": true,
  "webhook": {
    "id": "whep_9xk2m4p7",
    "workspace_id": "ws_abc123",
    "url": "https://example.com/hooks/dosya",
    "events": ["file.uploaded", "file.deleted", "share.accessed"],
    "description": "Slack notifier",
    "active": 1,
    "secret": "whsec_9f3k7x2m4p8q1r6s0t5u3v7w2y4z8a1b",
    "created_at": 1745312400
  }
}

Note: "secret" is only ever returned here (and from roll-secret) -
store it now, it can't be fetched again later.

curl -X POST https://api.dosya.dev/api/webhooks \
  -H "Authorization: Bearer dos_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws_abc123",
    "url": "https://example.com/hooks/dosya",
    "events": ["file.uploaded", "file.deleted", "share.accessed"],
    "description": "Slack notifier"
  }'

GET /api/webhooks List webhook endpoints

Query parameters (required):
  workspace_id=ws_abc123

200 OK

{
  "ok": true,
  "webhooks": [
    {
      "id": "whep_9xk2m4p7",
      "workspace_id": "ws_abc123",
      "url": "https://example.com/hooks/dosya",
      "events": ["file.uploaded", "file.deleted"],
      "description": "Slack notifier",
      "active": 1,
      "consecutive_failures": 0,
      "disabled_at": null,
      "created_by": "usr_xk2m9p4n",
      "created_at": 1745312400,
      "updated_at": 1745312400
    }
  ]
}

Note: the signing secret is never included in list or get responses.

curl "https://api.dosya.dev/api/webhooks?workspace_id=ws_abc123" \
  -H "Authorization: Bearer dos_your-api-key"

PATCH /api/webhooks/:id Update an endpoint

{
  "events": ["file.uploaded"],
  "active": false,
  "description": "Paused for maintenance"
}

200 OK

{
  "ok": true
}

curl -X PATCH https://api.dosya.dev/api/webhooks/whep_9xk2m4p7 \
  -H "Authorization: Bearer dos_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false
  }'

DELETE /api/webhooks/:id Delete an endpoint

No request body required.

200 OK

{
  "ok": true
}

curl -X DELETE https://api.dosya.dev/api/webhooks/whep_9xk2m4p7 \
  -H "Authorization: Bearer dos_your-api-key"

POST /api/webhooks/:id/roll-secret Rotate the signing secret

No request body required.

200 OK

{
  "ok": true,
  "secret": "whsec_2q8w4e6r1t3y5u7i9o0p2a4s6d8f0g2h"
}

Note: the old secret stops validating new deliveries immediately.

curl -X POST https://api.dosya.dev/api/webhooks/whep_9xk2m4p7/roll-secret \
  -H "Authorization: Bearer dos_your-api-key"

POST /api/webhooks/:id/test Send a test event

No request body required.

200 OK

{
  "ok": true,
  "delivery_id": "whd_7n2xm4kp"
}

A synthetic "file.uploaded" event (data.test: true) is queued and
delivered through the same pipeline as real events.

curl -X POST https://api.dosya.dev/api/webhooks/whep_9xk2m4p7/test \
  -H "Authorization: Bearer dos_your-api-key"

GET /api/webhooks/:id/deliveries View delivery logs

Query parameters (optional):
  page=1          Page number
  per_page=25     Results per page (10-100)

200 OK

{
  "ok": true,
  "deliveries": [
    {
      "id": "whd_3kp7n2xm",
      "event_id": "evt_9xk2m4p7",
      "event_type": "file.uploaded",
      "status": "success",
      "attempts": 1,
      "next_attempt_at": null,
      "last_attempt_at": 1745312401,
      "response_status": 200,
      "response_snippet": "ok",
      "error": null,
      "created_at": 1745312400
    }
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

curl https://api.dosya.dev/api/webhooks/whep_9xk2m4p7/deliveries \
  -H "Authorization: Bearer dos_your-api-key"

POST /api/webhooks/:id/deliveries/:deliveryId/redeliver Redeliver a failed event

No request body required.

200 OK

{
  "ok": true,
  "delivery_id": "whd_8m2k4p7n"
}

Queues a brand-new delivery (status "pending", attempts 0) carrying
the original event's payload.

curl -X POST https://api.dosya.dev/api/webhooks/whep_9xk2m4p7/deliveries/whd_3kp7n2xm/redeliver \
  -H "Authorization: Bearer dos_your-api-key"

Event catalog

file.uploaded A file finished uploading - a brand-new file, or a new version of an existing one. Fires no matter how the file arrived: web app, desktop sync, CLI, SFTP, WebDAV, or the S3 gateway.

{
  "id": "evt_9xk2m4p7",
  "type": "file.uploaded",
  "created": 1745312400,
  "workspace_id": "ws_abc123",
  "data": {
    "file_id": "file_8xk2m9p4",
    "name": "project-final.mp4",
    "size": 214748364800,
    "folder_id": "fld_2jd7m4qr",
    "version": 2,
    "is_new_version": true
  }
}

file.deleted A file was moved to trash (soft delete) or permanently erased. Fires for direct deletes and for every descendant file when a folder is deleted, across all access methods (web, WebDAV, S3, bulk operations).

{
  "id": "evt_3kp7n2xm",
  "type": "file.deleted",
  "created": 1745312450,
  "workspace_id": "ws_abc123",
  "data": {
    "file_id": "file_8xk2m9p4",
    "name": "project-final.mp4",
    "permanent": false
  }
}

share.accessed A share link was viewed or downloaded.

{
  "id": "evt_7n2xm4kp",
  "type": "share.accessed",
  "created": 1745312500,
  "workspace_id": "ws_abc123",
  "data": {
    "share_id": "share_9xm2k4p7",
    "token": "9xm2k4p7",
    "file_id": "file_8xk2m9p4",
    "access_type": "download"
  }
}

Delivery request

Every event is delivered as a single POST with a JSON body (the payload shown above) and these headers:

POST <your endpoint URL>
Content-Type: application/json
User-Agent: dosya-webhooks/1
X-Dosya-Signature: t=1745312400,v1=3f9c1a7e2b8d4f6a9c0e2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a
X-Dosya-Event-Id: evt_9xk2m4p7
X-Dosya-Event-Type: file.uploaded
X-Dosya-Delivery-Id: whd_3kp7n2xm

<JSON payload - see the event catalog above>

Verifying signatures

X-Dosya-Signature carries t=<unix-seconds>,v1=<hex-hmac>. Recompute HMAC_SHA256(secret, `${t}.${rawBody}`) over the raw, unparsed request body and compare it to v1 using a constant-time comparison.

Reject the request if the timestamp is more than 300 seconds (5 minutes) away from the current time - this blocks replayed deliveries.

import crypto from "node:crypto";

function verifyDosyaSignature(secret, rawBody, header) {
  // header looks like: "t=1745312400,v1=3f9c1a..."
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  const t = Number(parts.t);

  // Replay protection: reject signatures older than 5 minutes
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;

  const message = t + "." + rawBody;
  const expected = crypto.createHmac("sha256", secret).update(message).digest("hex");

  // Constant-time compare
  const a = Buffer.from(parts.v1, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Retries & auto-disable

A delivery counts as a success on any 2xx response. Otherwise it's retried up to 6 attempts total, with increasing backoff:

Immediate 1st attempt

30s 2nd attempt

2m 3rd attempt

10m 4th attempt

1h 5th attempt

6h 6th attempt

An endpoint that racks up too many consecutive failed attempts across events is automatically deactivated so it stops burning retries against a dead URL - re-enable it any time from the app or via PATCH /api/webhooks/:id. View delivery history per endpoint on the app's Webhooks integration page, or via GET /api/webhooks/:id/deliveries - failed deliveries can be redelivered from either place.

Limits

Storage limits

Two independent caps apply: your plan's total storage, and (optionally) a per-workspace max file size.

5 GB Free

100 GB Starter

500 GB Plus

1 TB Pro

2 TB Business

Numbers above are each plan's total storage. An upload that would push you over it is rejected with 400 Bad Request. Separately, a workspace can set its own max_file_size_gb cap on individual files (uncapped by default, configurable in workspace settings) - a file over that cap is rejected with 400 on the REST upload API, or 413 over S3 or WebDAV.

Limits

Rate limits

300 / min General API requests

20 / 60s Auth endpoints (login, signup, etc.)

300 / min Upload-init calls, per user

600 / min Sync-poll calls

600 / 60s Per-IP guard, all endpoints

Most API responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers (some exempt paths, e.g. desktop sync, webhooks, and upload data transfer, omit them). When a limit is exceeded, the response is 429 Too Many Requests with a Retry-After header (seconds) and body { "ok": false, "error": "Too many requests" }.

Versioning

API versioning

This API is unversioned - the base path is /api, with no version number in the URL or in request headers. Breaking changes are announced in the changelog ahead of time; non-breaking additions (new fields, new endpoints) may ship without notice.

dosya.dev REST API

Authentication

Response & error format

API Reference

Webhooks

Registering an endpoint

Retries & auto-disable

Storage limits

Rate limits

API versioning

Start integrating today