Skip to content
calternal docs

Create a public link

POST
/api/v1/files/links
curl --request POST \
  --url https://example.com/api/v1/files/links \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "clear_password": true, "expires_at": "example", "hide_filenames": true, "max_downloads": 1, "password": "example", "path": "example", "permissions": { "download": true, "linked_notes": true, "upload": true, "view": true }, "presentation": "example", "slug": "example" }'

Requires a signed-in User with the data scope and permission to share the selected Item. It returns 400 when the link settings are invalid or 403 when access is denied. Route: /api/v1/files/links. Inputs: . Do not automatically replay this operation after an uncertain result.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
clear_password

On update: remove the password. password: null keeps the current one, so turning a password off needs this explicit flag.

boolean
expires_at
string | null
hide_filenames
required
boolean
max_downloads
integer | null format: int64
password
string | null
path
required
string
permissions
required
object
download
required
boolean
linked_notes
required
boolean
upload
required
boolean
view
required
boolean
presentation
required
string
slug
string | null
Examplegenerated
{
  "clear_password": true,
  "expires_at": "example",
  "hide_filenames": true,
  "max_downloads": 1,
  "password": "example",
  "path": "example",
  "permissions": {
    "download": true,
    "linked_notes": true,
    "upload": true,
    "view": true
  },
  "presentation": "example",
  "slug": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
download_count
required
integer format: int64
expires_at
string | null
has_password
required
boolean
hide_filenames
required
boolean
id
required
string
last_access
string | null
max_downloads
integer | null format: int64
path
required
string
permissions
required
object
download
required
boolean
linked_notes
required
boolean
upload
required
boolean
view
required
boolean
presentation
required
string
slug
required
string
view_count
required
integer format: int64
Examplegenerated
{
  "download_count": 1,
  "expires_at": "example",
  "has_password": true,
  "hide_filenames": true,
  "id": "example",
  "last_access": "example",
  "max_downloads": 1,
  "path": "example",
  "permissions": {
    "download": true,
    "linked_notes": true,
    "upload": true,
    "view": true
  },
  "presentation": "example",
  "slug": "example",
  "view_count": 1
}

400

Section titled “400”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}