Storage API

Manage file storage for your organization. Upload, retrieve, and delete files via presigned URLs.

Every file has two names. The name is the one you sent and the one your app should show; the path is the key the file is stored under, which is its id. A download arrives named by the path, not by the name.

GET/organizations/:orgId/storages

List all storages in an organization.

Response

{
  "storages": [
    {
      "id": "stor_abc123",
      "name": "My Storage",
      "status": "active",
      "createdAt": "2026-03-20T...",
      "updatedAt": "2026-03-20T..."
    }
  ]
}

GET/organizations/:orgId/storages/:storageId/files

List files in a storage. Use the limit query parameter (1-200, default 50) and cursor for pagination.

Response

{
  "files": [
    {
      "id": "f1234567-abcd-...",
      "name": "photo.png",
      "path": "f1234567-abcd-...",
      "mime": "image/png",
      "size": 102400,
      "status": "active",
      "error": null,
      "createdAt": "2026-03-20T...",
      "updatedAt": "2026-03-20T..."
    }
  ],
  "nextCursor": null
}

POST/organizations/:orgId/storages/:storageId/files

Create file entries and get presigned upload URLs. Upload your files to the returned URLs within 1 hour.

One request prepares at most 100 files. Each name must be 1 to 128 characters, and each MIME type must contain a slash and be at most 255 characters. Anything outside that is a 400 naming which rule it broke, and no entries are created.

Request body

{
  "files": [
    { "name": "photo.png", "mime": "image/png" },
    { "name": "data.json", "mime": "application/json" }
  ]
}

Response

{
  "files": [
    {
      "id": "f1234567-abcd-...",
      "name": "photo.png",
      "path": "f1234567-abcd-...",
      "mime": "image/png",
      "size": 0,
      "status": "pending",
      "error": null,
      "createdAt": "2026-03-20T...",
      "updatedAt": "2026-03-20T...",
      "url": "https://upload.justdeploy.net/...", // Presigned upload URL
      "expiresAt": "2026-09-05T01:00:00.000Z"
    }
  ]
}

Upload your file to the presigned URL:

Upload

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @photo.png

expiresAt is the latest upload expiry; revocation can invalidate it earlier. The URL may be reused to overwrite the same file while valid. It is temporary permission: never log, cache or persist it, and never attach JustDeploy authentication headers.

GET/organizations/:orgId/storages/:storageId/files/:fileId

Get file metadata and a signed download URL. The URL expires in 1 hour.

Response

{
  "file": {
    "id": "f1234567-abcd-...",
    "name": "photo.png",
    "path": "f1234567-abcd-...",
    "mime": "image/png",
    "size": 102400,
    "status": "active",
    "error": null,
    "createdAt": "2026-03-20T...",
    "updatedAt": "2026-03-20T...",
    "url": "https://cdn.justdeploy.net/..." // Signed download URL
  }
}

DELETE/organizations/:orgId/storages/:storageId/files/:fileId

Delete a file from storage.