---
**📚 Main Documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt)
This is an individual endpoint documentation file. For the complete API reference, see the main documentation above.
---
# (GET) Get links
Retrieve links from your workspace with flexible filtering options. Filter by link ID, external ID, tenant ID, or partner ID.
**Category:** Links
## Endpoint

GET /api/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 and QR code URL.

**Endpoint**

```text
GET /api/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 | Location | Description                                                                                 |
| ---------- | ------------- | -------- | -------- | ------------------------------------------------------------------------------------------- |
| id         | string (UUID) | No       | query    | Filter by specific link ID. Returns a single link if found.                                 |
| externalId | string        | No       | query    | Filter by external ID. Useful for syncing with external systems.                            |
| tenantId   | string        | No       | query    | Filter by tenant ID for multi-tenant scenarios.                                             |
| partnerId  | string (UUID) | No       | query    | Filter by partner ID to retrieve all links associated with a specific partner.              |
| take       | number        | No       | query    | Number of results to return (default: 50, min: 1, max: 10,000).                             |
| skip       | number        | No       | query    | Number of results to skip for pagination (default: 0, min: 0).                              |
| sort       | string        | No       | query    | Sort order by createdAt: "asc" for oldest first, "desc" for newest first (default: "desc"). |

> **Warning: Request Limits**
> The `take` parameter supports values from 1 to 10,000. Requests above 10,000 are rejected.

## Status Codes

### 200

Successfully retrieved links.

**Request**

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

**Request**

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

**Response**

```json
[
	{
		"id": "550e8400-e29b-41d4-a716-446655440000",
		"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",
		"expiresAt": null,
		"expiredUrl": null,
		"password": null,
		"cloaked": false,
		"ios": null,
		"android": null,
		"geo": null,
		"createdAt": "2024-01-01T00:00:00Z"
	}
]
```

### 401

Invalid or missing API key.

**Request**

```bash
curl -X GET "https://hoko.to/api/links" \
  -H "Authorization: Bearer invalid_key"
```

**Request**

```javascript
const response = await fetch('https://hoko.to/api/links', {
	method: 'GET',
	headers: {
		Authorization: 'Bearer invalid_key'
	}
});
```

**Response**

```json
{
	"error": {
		"en": "Invalid API key",
		"ar": "مفتاح API غير صالح"
	}
}
```

### 403

API key does not have the required linksRead scope.

**Request**

```bash
curl -X GET "https://hoko.to/api/links" \
  -H "Authorization: Bearer <API_KEY>"
```

**Request**

```javascript
const response = await fetch('https://hoko.to/api/links', {
	method: 'GET',
	headers: {
		Authorization: 'Bearer <API_KEY>'
	}
});
```

**Response**

```json
{
	"error": {
		"en": "Missing required scopes",
		"ar": "الصلاحيات المطلوبة مفقودة"
	},
	"missingScopes": ["linksRead"]
}
```

### 429

Rate limit exceeded. Check X-RateLimit-\* headers for details.

**Request**

```bash
curl -X GET "https://hoko.to/api/links" \
  -H "Authorization: Bearer <API_KEY>"
```

**Request**

```javascript
const response = await fetch('https://hoko.to/api/links', {
	method: 'GET',
	headers: {
		Authorization: 'Bearer <API_KEY>'
	}
});
```

**Response**

```json
{
	"error": {
		"en": "Rate limit exceeded",
		"ar": "تم تجاوز حد المعدل"
	},
	"retryAfter": 60
}
```

## Examples

Here are practical examples of retrieving links:

**Request**

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

**Request**

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

**Response**

```json
[
	{
		"id": "550e8400-e29b-41d4-a716-446655440000",
		"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"
		},
		"collectionId": "550e8400-e29b-41d4-a716-446655440000",
		"externalId": "ext_123",
		"tenantId": "tenant_123",
		"partnerId": "550e8400-e29b-41d4-a716-446655440000",
		"createdAt": "2024-01-01T00:00:00Z"
	}
]
```

> **Info: 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.

---

**Back to main documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt)