Skip to main content
GET
/
api
/
v1
/
urls
List Your URLs
curl --request GET \
  --url https://spoo.me/api/v1/urls \
  --header 'Authorization: Bearer <token>'
{
  "items": [
    {
      "id": "<string>",
      "password_set": true,
      "alias": "<string>",
      "long_url": "<string>",
      "status": "<string>",
      "created_at": "<string>",
      "expire_after": 123,
      "max_clicks": 123,
      "private_stats": true,
      "block_bots": true,
      "total_clicks": 123,
      "last_click": "<string>"
    }
  ],
  "page": 123,
  "pageSize": 123,
  "total": 123,
  "hasNext": true,
  "sortBy": "<string>",
  "sortOrder": "<string>"
}

Authorizations

​
Authorization
string
header
required

API key authentication. Pass your key as: Bearer spoo_<your_key>

Query Parameters

​
page
integer
default:1

Page number (default: 1)

Required range: x >= 1
Example:

1

​
pageSize
integer
default:20

Items per page (default: 20, max: 100)

Required range: 1 <= x <= 100
Example:

20

​
sortBy
enum<string>
default:created_at

Field to sort by

Available options:
created_at,
last_click,
total_clicks
​
sortOrder
enum<string>
default:descending

Sort direction

Available options:
ascending,
asc,
1,
descending,
desc,
-1
​
filter
string | null

JSON string containing filter criteria for URLs. Format: {"field": value}

Available filter fields:

  • status — Filter by URL status ("ACTIVE" or "INACTIVE")
  • createdAfter — Filter URLs created after this date (ISO 8601 datetime or Unix timestamp)
  • createdBefore — Filter URLs created before this date (ISO 8601 datetime or Unix timestamp)
  • passwordSet — Filter by password protection (boolean: true/false)
  • maxClicksSet — Filter by click limit presence (boolean: true/false)
  • search — Search in alias or long_url (case-insensitive string)

Value formats:

  • status: String — "ACTIVE" or "INACTIVE" (case-sensitive)
  • createdAfter / createdBefore: ISO 8601 datetime string (e.g., "2024-01-01T00:00:00Z") or Unix timestamp (e.g., 1704067200)
  • passwordSet / maxClicksSet: Boolean — true or false
  • search: String — case-insensitive search term

Examples:

  • {"status": "ACTIVE"} — Only active URLs
  • {"passwordSet": true} — Only password-protected URLs
  • {"createdAfter": "2024-01-01T00:00:00Z"} — URLs created after Jan 1, 2024
  • {"status": "ACTIVE", "maxClicksSet": true} — Active URLs with click limits
  • {"search": "example"} — URLs containing "example" in alias or long_url
  • {"createdAfter": "2024-01-01", "createdBefore": "2024-12-31", "status": "ACTIVE"} — Active URLs from 2024
Example:

"{\"status\":\"ACTIVE\"}"

​
filterBy
string | null

Alias for filter parameter.

Response

Successful Response

Response body for GET /api/v1/urls.

Uses camelCase field names to match the existing Flask endpoint exactly. Field names are camelCase here (not snake_case + alias) because this is a response-only model — we build it explicitly in the route handler.

​
items
UrlListItem · object[]
required
​
page
integer
required
​
pageSize
integer
required
​
total
integer
required
​
hasNext
boolean
required
​
sortBy
string
required
​
sortOrder
string
required