---
**📚 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 partners
Retrieve partners by ID. Supports pagination and sorting.
**Category:** Partners
## Endpoint

GET /api/partners

Retrieve partners by id. Supports pagination with take, skip, and sorting by createdAt.

**Endpoint**

```text
GET /api/partners
```

## Authentication

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

## Query Parameters

| Parameter | Type          | Required | Location | Description                                                                                 |
| --------- | ------------- | -------- | -------- | ------------------------------------------------------------------------------------------- |
| id        | string (UUID) | No       | query    | Filter by specific partner ID. Returns a single partner if found.                           |
| take      | number        | No       | query    | Number of results to return (default: 50, min: 1, max: 5,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 5,000. Requests above 5,000 are rejected.

## Status Codes

### 200

Successfully retrieved partners.

**Request**

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

**Request**

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

**Response**

```json
[
	{
		"id": "550e8400-e29b-41d4-a716-446655440000",
		"name": "Partner Name",
		"email": "partner@example.com",
		"phone": "+1234567890",
		"createdAt": "2024-01-01T00:00:00Z",
		"updatedAt": "2024-01-01T00:00:00Z"
	}
]
```

### 400

Invalid query parameters. This includes invalid UUID filters or invalid `take`, `skip`, or `sort` values.

**Response**

```json
{
	"error": {
		"en": "Invalid request",
		"ar": "طلب غير صالح"
	}
}
```

### 401

Invalid or missing API key.

**Request**

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

**Request**

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

**Response**

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

### 403

API key does not have the required partnersRead scope.

**Request**

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

**Request**

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

**Response**

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

### 429

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

**Request**

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

**Request**

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

**Response**

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

### 500

Unexpected server error.

**Response**

```json
{
	"error": {
		"en": "Internal server error",
		"ar": "خطأ داخلي في الخادم"
	}
}
```

## Examples

**Request**

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

**Request**

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

**Response**

```json
[
	{
		"id": "550e8400-e29b-41d4-a716-446655440000",
		"name": "Partner Name",
		"email": "partner@example.com",
		"phone": "+1234567890",
		"createdAt": "2024-01-01T00:00:00Z",
		"updatedAt": "2024-01-01T00:00:00Z"
	}
]
```

---

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