Urlsome

API reference

The HTTP API behind Urlsome. JSON in, JSON out. 10 endpoints.

Overview

Short links for agents: the same operations the MCP server offers, for your own agent or a script. Authenticate with an API key from your account page: Authorization: Bearer sk_shortener_…. Every link stays editable: its destination, title and password can change after it is shared. New links get a random 6-character slug, or a chosen word: on this service's own domain up to 5 words per account without Pro, 6-64 characters, counted for the account's lifetime (403 not_available past them); Pro accounts any number, 4-64 characters; on a custom domain any slug works. A previous slug keeps redirecting. Short URLs answer 302 (never 301), so changes and clicks always reach us. Free: 1,000 new links per calendar month (UTC); a link with no click in 12 months expires (410) and its slug stays yours. Errors are JSON { error, message }; the monthly limit is 429 limit_reached.

Base URL

https://urlsome.com

Authentication

Send an API key in the Authorization header. Keys start with sk_shortener_. Create and revoke keys in your account. A key is shown once.

Authorization: Bearer sk_shortener_…

Links

Clicks of a link

GET/api/links/{link}/stats

Per day (UTC, oldest first) over 7, 30 or 90 days. Nothing about visitors is stored.

Path parameters

  • linkstringrequired

    The link's id or slug (on this service's own domain).

Query parameters

  • daysinteger

Example

curl 'https://urlsome.com/api/links/string/stats' \
  -H 'Authorization: Bearer sk_shortener_…'

Responses

200 Clicks.

{
  "link": {
    "id": "string",
    "short_url": "string",
    "domain": "string",
    "slug": "string",
    "url": "string",
    "title": "string",
    "clicks": 0,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "status": "active",
    "protected": true,
    "kind": "url",
    "file": {
      "name": "string",
      "size": 0,
      "type": "application/pdf"
    }
  },
  "days": 0,
  "total": 0,
  "series": [
    {
      "day": "string",
      "clicks": 0
    }
  ]
}

Files

Share a file behind a password

POST/api/files

Stores the file privately and returns a short link (kind: "file"). Whoever opens it enters the password, then the file opens in the browser. Counts as a new link and against the monthly allowance of shared files (100 on Free); the account stores up to 10 GB of files (429 storage_full past that: delete a shared file to free space).

Request body

  • filestring (binary)required

    PDF, PNG, JPEG, WebP or GIF, up to 100 MB, recognized by its bytes, streamed into storage as it arrives (send the text fields before it when you can). Archives, programs, web pages and SVG are refused.

  • passwordstringrequired

    At least 6 characters. At most 128 characters.

  • slugstring
  • titlestring

    At most 200 characters.

  • filenamestring

    The name shown when it opens (default: the uploaded file's).

Example

curl -X POST 'https://urlsome.com/api/files' \
  -H 'Authorization: Bearer sk_shortener_…' \
  -H 'Content-Type: application/json' \
  -d '{"file":"string","password":"string","slug":"string","title":"string","filename":"string"}'

Responses

201 The file link.

{
  "id": "string",
  "short_url": "string",
  "domain": "string",
  "slug": "string",
  "url": "string",
  "title": "string",
  "clicks": 0,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "status": "active",
  "protected": true,
  "kind": "url",
  "file": {
    "name": "string",
    "size": 0,
    "type": "application/pdf"
  }
}

400 Not an allowed file, or no valid password.

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

413 Larger than 100 MB.

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

429 The monthly allowance of shared files is used (`limit_reached`), the account stores 10 GB of files already (`storage_full`), or too many changes in a minute.

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

Replace a shared file

PUT/api/files/{link}

Replaces the file behind a file link. The short URL and the password stay (a password sent replaces it and closes open sessions). The new file takes the old one's place in the account's storage; it does not count as a new file.

Path parameters

  • linkstringrequired

    The link's id, slug or short URL.

Request body

  • filestring (binary)required

    PDF, PNG, JPEG, WebP or GIF, up to 100 MB, recognized by its bytes, streamed into storage as it arrives (send the text fields before it when you can). Archives, programs, web pages and SVG are refused.

  • passwordstring

    At least 6 characters. At most 128 characters.

  • filenamestring

    The name shown when it opens (default: the uploaded file's).

Example

curl -X PUT 'https://urlsome.com/api/files/string' \
  -H 'Authorization: Bearer sk_shortener_…' \
  -H 'Content-Type: application/json' \
  -d '{"file":"string","password":"string","filename":"string"}'

Responses

200 The file link.

{
  "id": "string",
  "short_url": "string",
  "domain": "string",
  "slug": "string",
  "url": "string",
  "title": "string",
  "clicks": 0,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "status": "active",
  "protected": true,
  "kind": "url",
  "file": {
    "name": "string",
    "size": 0,
    "type": "application/pdf"
  }
}

400 Not an allowed file, or not a file link.

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

404 Not one of your links.

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

413 Larger than 100 MB.

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

429 The new file would take the account past 10 GB of files (`storage_full`), or too many changes in a minute.

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