---
title: "List Public Retrievers"
method: GET
path: "/v1/public/retrievers/"
tags: ["Public Retriever API"]
---

# List Public Retrievers

`GET /v1/public/retrievers/`

List all public retrievers with pagination and search.

This endpoint allows browsing and discovering all published retrievers
across all organizations. No authentication required.

**Authentication:**
- NO authentication required - completely public endpoint
- Discover retrievers created by all Mixpeek users

**Pagination:**
- Default: page=1, page_size=20
- Maximum page_size: 100
- Returns total count and total pages

**Search:**
- Search across retriever titles and descriptions
- Case-insensitive regex matching
- Combine with pagination

**Filtering:**
- By default, only active retrievers are shown
- Set `include_inactive=true` to see all retrievers

**Response includes:**
- List of public retrievers with basic info
- Pagination details (page, page_size, total_count, total_pages)
- Aggregate statistics (total active, password protected, open)

**What's NOT exposed:**
- API keys (except in individual config endpoint)
- Internal IDs or organization details
- Full retriever configuration (use template endpoint for that)
- Password values (only password_protected: true/false)

**Example:**
```bash
# List all public retrievers (first page)
curl -X GET "https://api.mixpeek.com/v1/public/retrievers/"

# Search for video-related retrievers
curl -X GET "https://api.mixpeek.com/v1/public/retrievers/?search=video&page_size=50"

# Get page 2 with custom page size
curl -X GET "https://api.mixpeek.com/v1/public/retrievers/?page=2&page_size=50"
```

**Use Cases:**
- Browse available public retrievers
- Discover search patterns and implementations
- Find retrievers to use as templates
- Explore what others have built

## Query parameters

- `page` integer — Page number (1-indexed)
- `page_size` integer — Results per page
- `include_inactive` boolean — Include inactive retrievers in results
- `search` string, nullable — Search query for filtering by title or description

## Response `200`

Successful Response

- ListPublicRetrieversResponse — Response for listing public retrievers. Follows the same pattern as ListCollectionsResponse for consistent developer experience.
  - `results` PublicRetrieverListItem[], required — List of public retrievers
    - `public_name` string, required — Public URL-safe name used in the public URL
    - `public_url` string, required — Full public URL to the retriever page
    - `title` string, required — Display title from display_config
    - `description` string, nullable — Display description from display_config
    - `logo_url` string, nullable — Logo URL from display_config
    - `icon_base64` string, nullable — Base64 encoded icon/favicon from display_config
    - `og_image_url` string, nullable — Social preview/OG image URL from display_config
    - `password_protected` boolean, required — Whether password authentication is required
    - `is_active` boolean, required — Whether the retriever is active
    - `external_links` ExternalLink[] — External resource links (GitHub, blog posts, docs, etc.)
      - `name` string, required — Display name for the link
      - `url` string, required — URL to the external resource
    - `created_at` string, date-time, required — When the retriever was published
    - `updated_at` string, date-time, required — When the retriever was last updated
  - `total_count` integer, required — Total number of public retrievers matching the query
  - `page` integer, required — Current page number
  - `page_size` integer, required — Results per page
  - `total_pages` integer, required — Total number of pages
  - `stats` PublicRetrieverListStats — Aggregate statistics for public retrievers list.
    - `total_active` integer — Number of active public retrievers
    - `total_password_protected` integer — Number of password-protected retrievers
    - `total_open` integer — Number of fully open (no password) retrievers

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/5d4c905106b4/schema)