Skip to main content
Create shortened URLs or upload text content. This endpoint is part of Zipline’s URL shortening feature.

​
Endpoint

POST /api/user/urls

​
Authentication

Requires authentication via Bearer token in the Authorization header. 
Authorization: Bearer <your-token>

​
Request

​
JSON Body

​
destination
string
required
The destination URL to shorten or redirect to.
{
  "destination": "https://example.com/very/long/url/path"
}
​
vanity
string
Custom vanity path for the shortened URL (max 100 characters). Must be unique.
{
  "vanity": "my-link"
}
If vanity is already taken, the request will fail with a 400 error.
​
enabled
boolean
default:"true"
Whether the shortened URL is immediately active.
{
  "enabled": false
}

​
Headers

​
X-Zipline-Max-Views
number
Maximum number of times the URL can be accessed before it’s disabled.
X-Zipline-Max-Views: 100
​
X-Zipline-Password
string
Protect the URL with a password. Users must enter this password before being redirected.
X-Zipline-Password: secret123
​
X-Zipline-Domain
string
Override the return domain. Supports multiple domains separated by commas (randomly selected).
X-Zipline-Domain: short.example.com,links.example.com
​
X-Zipline-No-Json
boolean
default:"false"
Return plain text URL instead of JSON response.
X-Zipline-No-Json: true

​
Response

​
JSON Response (default)

​
id
string
required
Unique identifier for the shortened URL.
​
code
string
required
Generated short code for the URL.
​
vanity
string
Custom vanity path if provided.
​
destination
string
required
The destination URL.
​
userId
string
required
ID of the user who created the URL.
​
enabled
boolean
required
Whether the URL is currently active.
​
maxViews
number
Maximum views limit if set.
​
views
number
required
Current number of views.
​
createdAt
string
required
ISO 8601 timestamp of creation.
​
url
string
required
Full shortened URL.

​
Plain Text Response

When X-Zipline-No-Json: true is set, returns the shortened URL directly: 
https://short.example.com/abc123

​
Examples

​
Basic URL Shortening

curl -X POST https://your-zipline.com/api/user/urls \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "https://example.com/very/long/url/path"
  }'

​
Vanity URL

curl -X POST https://your-zipline.com/api/user/urls \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "https://github.com/user/repo",
    "vanity": "my-repo"
  }'

​
Password Protected URL

curl -X POST https://your-zipline.com/api/user/urls \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Zipline-Password: secret123" \
  -d '{
    "destination": "https://private-docs.example.com"
  }'

​
Limited Views URL

curl -X POST https://your-zipline.com/api/user/urls \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Zipline-Max-Views: 10" \
  -d '{
    "destination": "https://one-time-link.example.com"
  }'

​
Plain Text Response

curl -X POST https://your-zipline.com/api/user/urls \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Zipline-No-Json: true" \
  -d '{
    "destination": "https://example.com"
  }'

​
Response Example

{
  "id": "clx7g8kj30001abc123xyz",
  "code": "a8c3e9f2",
  "vanity": null,
  "destination": "https://example.com/very/long/url/path",
  "userId": "clx7a1kj30001xyz789abc",
  "enabled": true,
  "maxViews": null,
  "views": 0,
  "createdAt": "2024-03-03T12:00:00.000Z",
  "url": "https://short.example.com/a8c3e9f2"
}

​
Search URLs

You can also retrieve your shortened URLs: 
GET /api/user/urls?searchField=destination&searchQuery=example

​
Query Parameters

​
searchField
string
default:"destination"
Field to search: destination, vanity, or code.
​
searchQuery
string
Search term (case-insensitive, partial match).

​
Error Responses

​
400 Bad Request

  • Missing destination field
  • Vanity path already taken
  • Invalid request body

​
403 Forbidden

  • Creating URL would exceed user quota limit

​
Notes

The length of the generated short code is configured by the server’s urls.length setting.
If you have a user quota configured, creating URLs counts towards your maxUrls limit.
URLs with enabled: false return a 404 when accessed until you enable them.
Vanity paths must be unique across all users. Choose carefully!

Build docs developers (and LLMs) love

Get started for freeTalk to us