Skip to main content
Authentication Required: These endpoints require ADMIN or SUPERADMIN role.

​
List Users

GET /api/users

Get a list of all users in the system.

​
Request

​
noincl
boolean
default:"false"
Exclude the requesting admin user from the results
curl -X GET https://your-zipline.com/api/users \
  -H "Authorization: YOUR_ADMIN_TOKEN"
Get users excluding yourself
curl -X GET "https://your-zipline.com/api/users?noincl=true" \
  -H "Authorization: YOUR_ADMIN_TOKEN"

​
Response

Returns an array of user objects.
Example Response
[
  {
    "id": "clxxx123456789",
    "username": "john_doe",
    "role": "USER",
    "avatar": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "quota": null
  },
  {
    "id": "clxxx987654321",
    "username": "jane_admin",
    "role": "ADMIN",
    "avatar": "data:image/png;base64,...",
    "createdAt": "2024-01-10T08:15:00.000Z",
    "quota": {
      "filesQuota": "BY_BYTES",
      "maxBytes": "50gb",
      "maxFiles": null,
      "maxUrls": 100
    }
  }
]

​
Create User

POST /api/users

Create a new user account. Optionally set their role and avatar.

​
Request

​
username
string
required
Unique username for the new user
​
password
string
required
Password for the new user (will be hashed)
​
avatar
string
Base64-encoded image or URL for user avatar. Falls back to server default avatar if not provided.
​
role
string
default:"USER"
User role: USER, ADMIN, or SUPERADMIN
You can only create users with roles lower than or equal to your own role.
​
noincl
boolean
default:"false"
Same as GET endpoint - affects response format
curl -X POST https://your-zipline.com/api/users \
  -H "Authorization: YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "password": "securePassword123",
    "role": "USER"
  }'

​
Response

Returns the created user object.
Example Response
{
  "id": "clyyy111222333",
  "username": "newuser",
  "role": "USER",
  "avatar": "data:image/png;base64,...",
  "createdAt": "2024-03-15T12:00:00.000Z",
  "quota": null
}

​
Errors

  • 400 Bad Request: Username already exists
  • 403 Forbidden: Attempting to create a role higher than your own
  • 429 Too Many Requests: Rate limit exceeded (1 request per second)

​
Rate Limiting

This endpoint is rate-limited to 1 request per second.

​
Get User

GET /api/users/:id

Retrieve detailed information about a specific user.

​
Request

curl -X GET https://your-zipline.com/api/users/clxxx123456789 \
  -H "Authorization: YOUR_ADMIN_TOKEN"

​
Response

Example Response
{
  "id": "clxxx123456789",
  "username": "john_doe",
  "role": "USER",
  "avatar": null,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-03-10T14:20:00.000Z",
  "view": {
    "enabled": true,
    "embedColor": "#3b82f6"
  },
  "quota": {
    "id": "clqqq111222333",
    "filesQuota": "BY_BYTES",
    "maxBytes": "10gb",
    "maxFiles": null,
    "maxUrls": 50
  }
}

​
Errors

  • 404 Not Found: User not found

​
Update User

PATCH /api/users/:id

Update user profile, role, password, or quota settings.

​
Request

​
username
string
New username (must be unique)
​
password
string
New password (will be hashed)
​
avatar
string
New avatar URL
​
role
string
New role: USER, ADMIN, or SUPERADMIN
You can only assign roles lower than or equal to your own role.
​
quota
object
User quota configuration
Update role and quota
curl -X PATCH https://your-zipline.com/api/users/clxxx123456789 \
  -H "Authorization: YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "ADMIN",
    "quota": {
      "filesType": "BY_BYTES",
      "maxBytes": "50gb",
      "maxUrls": 200
    }
  }'
Remove quota limits
curl -X PATCH https://your-zipline.com/api/users/clxxx123456789 \
  -H "Authorization: YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quota": {
      "filesType": "NONE"
    }
  }'

​
Response

Returns the updated user object.

​
Errors

  • 400 Bad Request: Invalid quota configuration (e.g., BY_BYTES without maxBytes)
  • 403 Forbidden: Attempting to assign a role higher than your own
  • 404 Not Found: User not found

​
Delete User

DELETE /api/users/:id

Delete a user account. Optionally delete all their files and URLs.

​
Request

​
delete
boolean
default:"false"
If true, also deletes all files and URLs owned by the user from storage. If false, only the user account is deleted (files/URLs become orphaned).
Delete user only
curl -X DELETE https://your-zipline.com/api/users/clxxx123456789 \
  -H "Authorization: YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "delete": false
  }'
Delete user and all their content
curl -X DELETE https://your-zipline.com/api/users/clxxx123456789 \
  -H "Authorization: YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "delete": true
  }'

​
Response

Returns the deleted user object.
Example Response
{
  "id": "clxxx123456789",
  "username": "john_doe",
  "role": "USER",
  "avatar": null,
  "createdAt": "2024-01-15T10:30:00.000Z"
}

​
Errors

  • 403 Forbidden:
    • Attempting to delete yourself
    • Attempting to delete a user with a role equal to or higher than yours
  • 404 Not Found: User not found
Deletion is permanent and cannot be undone. When delete: true is set, all files are removed from the datasource (S3, local storage, etc.).

​
Role Hierarchy

The role system enforces a hierarchy:
  • SUPERADMIN: Can manage all users including other admins
  • ADMIN: Can manage users with USER role only
  • USER: Cannot access these endpoints
You cannot:
  • Create or assign roles higher than your own
  • Modify or delete users with roles equal to or higher than yours
  • Delete your own account through this endpoint

Build docs developers (and LLMs) love

Get started for freeTalk to us