(GET) Get links

Retrieve links from your workspace with flexible filtering options. Filter by link ID, external ID, tenant ID, or partner ID.

Endpoint

GET /links

Retrieve links from your workspace with flexible filtering options. Filter by link ID, external ID, tenant ID, or partner ID to find exactly what you need.

The endpoint supports efficient pagination and sorting, making it easy to browse large link libraries. Results are returned as an array of link objects, each containing complete link information including the generated short URL, QR code URL, collection ID, and assigned tag IDs.

Endpoint text

GET /links

Authentication

Requires authentication with an API key that has the linksRead scope.

Query Parameters

All parameters are optional. Use them to filter and paginate results.

Parameter	Type	Required	Description
`id` (query)	string (ULID)	No	Filter by specific link ID. Returns a single link if found.
`externalId` (query)	string	No	Filter by external ID. Useful for syncing with external systems.
`tenantId` (query)	string	No	Filter by tenant ID for multi-tenant scenarios.
`partnerId` (query)	string (ULID)	No	Filter by partner ID to retrieve all links associated with a specific partner.
`take` (query)	number	No	Number of results to return (default: 50, min: 1, max: 5,000).
`skip` (query)	number	No	Number of results to skip for pagination (default: 0, min: 0).
`sort` (query)	string	No	Sort order by createdAt: "asc" for oldest first, "desc" for newest first (default: "desc").

Request Limits

The `take` parameter supports values from 1 to 5,000. Requests above 5,000 are rejected.

Examples

Here are practical examples of retrieving links:

Request cURL

curl -X GET "https://api.hoko.to/links?take=50&sort=desc" \
  -H "Authorization: Bearer <API_KEY>"

Request JavaScript

const response = await fetch('https://api.hoko.to/links?take=50&sort=desc', {
	method: 'GET',
	headers: {
		Authorization: 'Bearer <API_KEY>'
	}
});
const links = await response.json();

Response json

[
	{
		"id": "<link_id>",
		"url": "https://example.com",
		"shortUrl": "https://hoko.to/abc123",
		"qrCode": "https://hoko.to/qrcode?text=https%3A%2F%2Fhoko.to%2Fabc123%3Fqr%3D1&size=512&errorCorrection=H&foreground=000000&background=FFFFFF&margin=1&format=svg",
		"title": "Example Link",
		"description": "An example link",
		"image": "https://example.com/image.jpg",
		"utm": {
			"source": "google",
			"medium": "cpc",
			"campaign": "summer",
			"term": "keyword",
			"content": "ad_content"
		},
		"expiresAt": null,
		"expiredUrl": null,
		"password": null,
		"cloaked": false,
		"ios": null,
		"android": null,
		"geo": null,
		"collectionId": "<collection_id>",
		"tagIds": ["<tag_id>"],
		"externalId": "ext_123",
		"tenantId": "tenant_123",
		"partnerId": "<partner_id>",
		"createdAt": "2024-01-01T00:00:00Z"
	}
]

Filtering Tips

You can combine multiple filters (id, externalId, tenantId, partnerId) in a single request. When multiple filters are provided, results match any of the specified filters. Use pagination (take/skip) to efficiently browse large result sets.