---
title: "Search Public Exercises"
method: GET
path: "/public-exercises/search"
tags: ["public_exercises"]
---

# Search Public Exercises

`GET /public-exercises/search`

Hybrid vector + keyword search over `public_exercises`.

The search core (embed → vector KNN → keyword regex → RRF merge → hydrate
+ gate) lives in `services/exercise_library_search.py`, shared with the
chat tool `search_exercise_library`.

The response shape mirrors `GET /public-exercises` so callers can reuse the
existing `PublicExerciseOut` type.

## Query parameters

- `q` string, required — Free-text search query.
- `category_path` string[], nullable — Prefix filter on category_path (repeat the query param per segment). Results are post-filtered to rows whose category_path starts with these segments.
- `difficulty` string, nullable — Exact-match filter on difficulty (easy/medium/hard).
- `type` 'exercice' | 'automatisme' | 'application_du_cours', nullable — Exact-match filter on type.
- `library` 'excellence' | 'cpge' | 'remediation', nullable — Admin-only library override. Non-admin callers stay gated by `library_filter_for(user)` regardless of this param.
- `subject` 'maths' | 'physique-chimie', nullable — Scope search to a matière (see list endpoint).
- `top_n` integer — Max number of results.

## Response `200`

Successful Response

- PublicExerciseOut[]
  - `id` string, required
  - `themes` string[], required
  - `content` string, required
  - `solution` string, required
  - `figure_content` string, nullable
  - `figure_solution` string, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `sequence_number` integer, nullable
  - `difficulty` string, nullable
  - `category_path` string[]
  - `subject` 'maths' | 'physique-chimie'
  - `diagnostic_info` DiagnosticInfoOut
    - `explanation` string, required
  - `library` 'excellence' | 'cpge' | 'remediation'
  - `type` 'exercice' | 'automatisme' | 'application_du_cours'
  - `cpge` RoutersPublicExercisesCpgeMetadata — CPGE-specific fields, present only when `library == "cpge"`. Grouped into a subdoc so that readers of a regular public exercise don't have to reason about hints / banque at all — those are genuinely prepa-only concerns.
    - `hints` string[]
    - `banque` string, nullable
  - `likes_count` integer
  - `savoirs_faire_ids` string[]
  - `title` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/excellence-ai/apis/excellence-learning.md) · [All operations](https://skmtc.dev/excellence-ai/apis/excellence-learning/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/excellence-ai/excellence-learning/revisions/437cd8414e9e/schema)