List Links

Retrieve a paginated list of your links.


GET /api/v1/links

Authentication

Required.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number (min: 1)
`per_page`	integer	20	Items per page (min: 1, max: 100)
`search`	string	—	Search by URL, short code, or title
`is_active`	string	—	Filter by active status: `"true"` or `"false"`

Response

Returns an array of link objects with pagination metadata.

Examples

Basic List


curl "https://snipurl.click/api/v1/links?page=1&per_page=20" \
  -H "Authorization: Bearer snip_live_your_key_here"


const response = await fetch(
  'https://snipurl.click/api/v1/links?page=1&per_page=20',
  { headers: { 'Authorization': 'Bearer snip_live_your_key_here' } }
);
const { data, meta } = await response.json();
console.log(`Showing ${data.length} of ${meta.total} links`);


import requests
 
response = requests.get(
    'https://snipurl.click/api/v1/links',
    headers={'Authorization': 'Bearer snip_live_your_key_here'},
    params={'page': 1, 'per_page': 20},
)
result = response.json()
print(f"Showing {len(result['data'])} of {result['meta']['total']} links")

Response (200 OK):


{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "short_code": "a8Kx2m",
      "short_url": "https://snipurl.click/a8Kx2m",
      "original_url": "https://example.com/article",
      "title": "Example Article",
      "is_active": true,
      "has_password": false,
      "expires_at": null,
      "clicks_count": 142,
      "analytics_public": false,
      "created_at": "2025-06-20T10:00:00.000Z",
      "updated_at": "2025-06-20T10:00:00.000Z"
    },
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "short_code": "team-doc",
      "short_url": "https://snipurl.click/team-doc",
      "original_url": "https://docs.google.com/document/d/abc",
      "title": "Team Document",
      "is_active": true,
      "has_password": true,
      "expires_at": "2025-12-31T23:59:59.000Z",
      "clicks_count": 23,
      "analytics_public": false,
      "created_at": "2025-06-18T15:30:00.000Z",
      "updated_at": "2025-06-18T15:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 142,
    "total_pages": 8
  }
}

Search and Filter


# Search for links containing "github"
curl "https://snipurl.click/api/v1/links?search=github" \
  -H "Authorization: Bearer snip_live_your_key_here"
 
# Only inactive links
curl "https://snipurl.click/api/v1/links?is_active=false" \
  -H "Authorization: Bearer snip_live_your_key_here"
 
# Large page with search
curl "https://snipurl.click/api/v1/links?per_page=100&search=docs" \
  -H "Authorization: Bearer snip_live_your_key_here"

Pagination

Use meta.total_pages to determine how many pages exist. Iterate through pages to fetch all links:


async function getAllLinks(apiKey) {
  const allLinks = [];
  let page = 1;
  let totalPages = 1;
 
  while (page <= totalPages) {
    const response = await fetch(
      `https://snipurl.click/api/v1/links?page=${page}&per_page=100`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    const { data, meta } = await response.json();
    allLinks.push(...data);
    totalPages = meta.total_pages;
    page++;
  }
 
  return allLinks;
}

Error Responses

Status	Code	Description
400	`VALIDATION_ERROR`	Invalid query parameters