REST API quickstart

Everything the slim.to dashboard does is backed by a JSON API at https://slim.to. The full OpenAPI spec is served at https://slim.to/docs/api (Swagger UI); the raw JSON is at https://slim.to/openapi/openapi.json.

Auth

Create a personal API key and send it as X-API-Key:

export SLIMTO_API_KEY=slim_your_key_here

Shorten a URL

curl -s -X POST https://slim.to/api/v1/links \
  -H "X-API-Key: $SLIMTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://example.com/pitch", "title": "Pitch deck"}'

Response (trimmed):

{
  "id": "52cab9d5-…",
  "slug": "x0b31u",
  "short_url": "https://slim.to/x0b31u",
  "type": "redirect",
  "is_active": true
}

Optional body fields:

Many at once: POST /api/v1/links/bulk with {"links": [{"target_url": "…", "title": "…", "slug": "…"}, …], "domain": "…"} creates up to 1000 redirect links in one request and returns {"created": n, "failed": n, "results": [...]} with a per-item outcome.

Upload a file → hosted link

Multipart upload; returns the file record and the hosted link in one call:

curl -s -X POST https://slim.to/api/v1/files \
  -H "X-API-Key: $SLIMTO_API_KEY" \
  -F "file=@report.pdf" \
  -F "title=Q3 Report"

Optional form fields: slug, password, domain, tags (a JSON array or a comma-separated list).

Allowed types: pdf, png, jpg, jpeg, gif, html, zip, mp4, and Office documents — docx, pptx, xlsx, doc, ppt, xls. Max 100 MB.

Office files are download-and-track only: page-level read analytics needs a renderer, which today means a PDF or a hosted page.

Files over 30 MB must use the two-step flow (the single-request path is capped by the hosting platform):

# 1. Get a signed upload URL
curl -s -X POST https://slim.to/api/v1/files/upload-url \
  -H "X-API-Key: $SLIMTO_API_KEY" -H "Content-Type: application/json" \
  -d '{"filename": "demo.mp4"}'
# → {"storage_key": "...", "upload_url": "...", "token": "...", "content_type": "video/mp4"}

# 2. PUT the file to upload_url
curl -s -X PUT "<upload_url>" -H "Content-Type: video/mp4" --data-binary @demo.mp4

# 3. Confirm — creates the File + Link records
curl -s -X POST https://slim.to/api/v1/files/confirm \
  -H "X-API-Key: $SLIMTO_API_KEY" -H "Content-Type: application/json" \
  -d '{"storage_key": "<storage_key>", "filename": "demo.mp4", "title": "Demo video"}'

confirm takes the same optional fields as the direct upload (slug, password, domain, tags). Ignore token unless the upload_url you were given says otherwise; it is there for storage backends that need it.

Replace the file behind a link

Publish a new version without changing the URL or losing its analytics:

curl -s -X POST https://slim.to/api/v1/links/<link_id>/replace-file \
  -H "X-API-Key: $SLIMTO_API_KEY" \
  -F "file=@report-v2.pdf"

The previous file is overwritten and is not recoverable. DELETE /api/v1/files/<file_id> removes an uploaded file outright.

List your links

curl -s "https://slim.to/api/v1/links?q=report&tag=q3&status=active&page=1&per_page=20" \
  -H "X-API-Key: $SLIMTO_API_KEY"

Returns {"links": [...], "total": n, "page": 1, "per_page": 20, "pages": n}. q searches slug, title, and target URL. Narrow the list further with tag (exact tag, case-insensitive), domain, status (active or disabled) and team_id; filters apply before pagination, so total and pages reflect them.

For autocomplete, GET /api/v1/links/suggest?q=rep returns up to eight matching links plus the tags, domains and teams you can filter on. With an empty q it returns the full facet lists and your most recent links.

Analytics for a link

curl -s https://slim.to/api/v1/analytics/links/<link_id> \
  -H "X-API-Key: $SLIMTO_API_KEY"

Returns totals (total_views, unique_viewers, avg_time_seconds, median_time_seconds, bounce_rate, total_downloads, last_viewed_at), breakdowns (device_breakdown, browser_breakdown, os_breakdown, country_breakdown, region_breakdown, city_breakdown, referrer_breakdown, per-page page_breakdown plus completion_rate for PDFs), a 30-day daily_views series, a viewers roster grouped by email or device signature, and per-session detail in sessions (most recent 200; sessions_total has the full count). Add /export to the path for CSV (Pro). Visits by the link's owner and active teammates are recorded but hidden from every analytics response by default; add include_own=1 to count them, labelled you or team.

More analytics endpoints:

To get pushed instead of polling, set up a webhook.

Custom domains

# Add — returns the DNS record to create, status "pending"
curl -s -X POST https://slim.to/api/v1/domains \
  -H "X-API-Key: $SLIMTO_API_KEY" -H "Content-Type: application/json" \
  -d '{"custom_domain": "share.example.com"}'

# Verify once DNS is in place
curl -s -X POST https://slim.to/api/v1/domains/<domain_id>/verify \
  -H "X-API-Key: $SLIMTO_API_KEY"

GET /api/v1/domains lists yours with status (pending or verified); DELETE /api/v1/domains/<domain_id> removes one. Pass a verified domain as domain when creating links. Custom domains need a Pro or Team plan.

Other useful endpoints

Hosted pages (/api/v1/pages, /api/v1/links/<id>/page) are in beta and documented only in the OpenAPI spec for now.

Errors

Errors are JSON: {"error": "message"} with a conventional status code: