ShareLink¶

Public secure-share links: time-limited, optionally password protected, with download counters.

All endpoints below are mounted under /api. Authentication: Authorization: Bearer <token> unless noted as public.

Endpoint count: 7

Endpoints¶

Method	Path	Handler	Guards
`POST`	`/api/sharelink/install`	`installShareLink`	RequireSuperuser()
`POST`	`/api/sharelink/settings`	`updateShareLinkSettings`	RequireSuperuser()
`GET`	`/api/sharelink/shares`	`listShareLinkShares`	RequireSuperuser()
`POST`	`/api/sharelink/shares`	`createShareLinkShare`	RequireSuperuser()
`DELETE`	`/api/sharelink/shares/:id`	`deleteShareLinkShare`	RequireSuperuser()
`GET`	`/api/sharelink/status`	`getShareLinkStatus`	RequireSuperuser()
`POST`	`/api/sharelink/uninstall`	`uninstallShareLink`	RequireSuperuser()

Source¶

Handlers for this section live in api/routes/handlers_*.go in the StarkOne source. Each handler binds its request body with gin.ShouldBindJSON(&req) and responds with the standard envelope:

{ "data": { ... } }

On error:

{ "error": { "code": "string", "message": "string" } }

Reference¶

`POST /api/sharelink/install`¶

Downloads the ShareLink binary, writes a systemd unit, and enables and starts the starkone-sharelink service.

Guards: RequireSuperuser()

Request body

{ "port": "string (optional)" }

Field	Type	Required	Description
`port`	string	no	Listen port for the ShareLink service. Defaults to `4443` when omitted or empty.

Response - 200 OK

{ "data": { "success": true, "message": "ShareLink installed and started", "port": "4443" } }

Errors

Status	Code	Meaning
`500`	`download_failed`	The `curl` download of the ShareLink binary failed; message contains the command output.
`500`	`service_failed`	Writing the systemd unit file failed.
`500`	`start_failed`	`systemctl start` of the service failed; message contains the command output.

Side effects

Runs curl -fsSL https://dl.starkone.io/binaries/starkone-sharelink -o /usr/sbin/starkone-sharelink and chmod 0755 on the binary.
Persists the chosen port in settings under key sharelink_port.
Writes the systemd unit /lib/systemd/system/starkone-sharelink.service.
Runs systemctl daemon-reload, systemctl enable starkone-sharelink, and systemctl start starkone-sharelink.

Example

curl -X POST https://panel.example.com:2087/api/sharelink/install \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"port": "4443"}'

`POST /api/sharelink/settings`¶

Validates and persists a new ShareLink listen port, restarting the service if it is currently running.

Guards: RequireSuperuser()

Request body

{ "port": "string (required)" }

Field	Type	Required	Description
`port`	string	yes	Listen port. Must parse to an integer in the range 1-65535.

Response - 200 OK

{ "data": { "success": true, "port": "4443" } }

Errors

Status	Code	Meaning
`400`	`bad_request`	Body could not be bound or `port` was empty (message: "port is required").
`400`	`bad_request`	`port` is not a valid integer between 1 and 65535 (message: "invalid port number").

Side effects

Persists the port in settings under key sharelink_port.
If the service is active (systemctl is-active --quiet starkone-sharelink), runs systemctl restart starkone-sharelink.

Example

curl -X POST https://panel.example.com:2087/api/sharelink/settings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"port": "4443"}'

`GET /api/sharelink/shares`¶

Lists configured share links, optionally filtered by website, with a computed expired flag per share.

Guards: RequireSuperuser()

Query parameters

Name	Type	Optional	Description
`website_id`	string	yes	When provided, only shares whose `website_id` matches are returned. Otherwise all shares are returned.

Response - 200 OK

{
  "data": [
    {
      "id": 1,
      "token": "a1b2c3...",
      "website_id": 42,
      "username": "user1",
      "uid": 1000,
      "gid": 1000,
      "path": "/home/user1/public",
      "permission": "read",
      "track_changes": false,
      "expires_at": "2026-12-31 23:59:59",
      "created_at": "2026-06-17 10:00:00",
      "description": "Quarterly report",
      "expired": false
    }
  ]
}

Note: website_id is only present in an item when the stored value is non-null. expired is computed by comparing expires_at (parsed as 2006-01-02 15:04:05) against the current time.

Errors

Status	Code	Meaning
`500`	`db_error`	The database query failed; message contains the SQL error.

Example

curl -X GET "https://panel.example.com:2087/api/sharelink/shares?website_id=42" \
  -H "Authorization: Bearer $TOKEN"

`POST /api/sharelink/shares`¶

Creates a new share link, generating a random 32-byte hex token and persisting the share record.

Guards: RequireSuperuser()

Request body

{
  "website_id": "int (optional)",
  "username": "string (required)",
  "uid": "int (optional)",
  "gid": "int (optional)",
  "path": "string (required)",
  "permission": "string (optional)",
  "track_changes": "bool (optional)",
  "expires_at": "string (optional)",
  "description": "string (optional)"
}

Field	Type	Required	Description
`website_id`	int (nullable)	no	Associated website id. Stored as NULL when omitted.
`username`	string	yes	Owner username for the shared path.
`uid`	int	no	Numeric user id used by the share.
`gid`	int	no	Numeric group id used by the share.
`path`	string	yes	Filesystem path being shared.
`permission`	string	no	Access permission. Defaults to `read` when empty.
`track_changes`	bool	no	Whether to track changes. Stored as 0/1.
`expires_at`	string	no	Expiry timestamp (`2006-01-02 15:04:05`). Stored as NULL when empty.
`description`	string	no	Human-readable description.

Response - 201 Created

{
  "data": {
    "id": 1,
    "token": "a1b2c3...",
    "path": "/home/user1/public",
    "permission": "read",
    "track_changes": false,
    "expires_at": "2026-12-31 23:59:59",
    "port": "4443"
  }
}

Note: this handler returns HTTP 201, not 200.

Errors

Status	Code	Meaning
`400`	`bad_request`	Body could not be bound (message: "Invalid request body").
`400`	`bad_request`	`path` or `username` was empty (message: "path and username are required").
`500`	`token_error`	Failed to generate the random token.
`500`	`db_error`	The INSERT failed; message contains the SQL error.

Side effects

Inserts a row into the sharelink_shares table.

Example

curl -X POST https://panel.example.com:2087/api/sharelink/shares \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "user1", "path": "/home/user1/public", "permission": "read"}'

`DELETE /api/sharelink/shares/:id`¶

Deletes the share link with the given id.

Guards: RequireSuperuser()

Path parameters

Name	Type	Description
`id`	string	The id of the share to delete.

Response - 200 OK

{ "data": { "success": true } }

Note: the handler does not check whether a row was actually deleted; a non-existent id still returns success.

Errors

Status	Code	Meaning
`500`	`db_error`	The DELETE failed; message contains the SQL error.

Side effects

Deletes the matching row from the sharelink_shares table.

Example

curl -X DELETE https://panel.example.com:2087/api/sharelink/shares/1 \
  -H "Authorization: Bearer $TOKEN"

`GET /api/sharelink/status`¶

Reports whether the ShareLink binary is installed, whether its service is running, and the configured port.

Guards: RequireSuperuser()

Response - 200 OK

{ "data": { "installed": true, "running": true, "port": "4443" } }

Note: installed reflects existence of /usr/sbin/starkone-sharelink; running reflects systemctl is-active --quiet starkone-sharelink; port falls back to 4443 when unset.

Example

curl -X GET https://panel.example.com:2087/api/sharelink/status \
  -H "Authorization: Bearer $TOKEN"

`POST /api/sharelink/uninstall`¶

Stops and disables the ShareLink service and removes its binary and systemd unit.

Guards: RequireSuperuser()

Response - 200 OK

{ "data": { "success": true, "message": "ShareLink uninstalled" } }

Side effects

Runs systemctl stop starkone-sharelink and systemctl disable starkone-sharelink.
Removes /usr/sbin/starkone-sharelink and /lib/systemd/system/starkone-sharelink.service.
Runs systemctl daemon-reload.

Example

curl -X POST https://panel.example.com:2087/api/sharelink/uninstall \
  -H "Authorization: Bearer $TOKEN"

ShareLink¶

Endpoints¶

Source¶

Reference¶

POST /api/sharelink/install¶

POST /api/sharelink/settings¶

GET /api/sharelink/shares¶

POST /api/sharelink/shares¶

DELETE /api/sharelink/shares/:id¶

GET /api/sharelink/status¶

POST /api/sharelink/uninstall¶

`POST /api/sharelink/install`¶

`POST /api/sharelink/settings`¶

`GET /api/sharelink/shares`¶

`POST /api/sharelink/shares`¶

`DELETE /api/sharelink/shares/:id`¶

`GET /api/sharelink/status`¶

`POST /api/sharelink/uninstall`¶