feat(api): consistent POST /search endpoints for engrams, episodes, and entities#1
Merged
feat(api): consistent POST /search endpoints for engrams, episodes, and entities#1
Conversation
GET requests with large query bodies are technically undefined behavior in HTTP. Move semantic search to POST /v1/engrams/search with a JSON body containing query, limit, detail, and level fields. GET /v1/engrams remains for listing all engrams (with optional threshold filter). The query path is removed from that handler. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2 tasks
Extend the search-as-POST pattern from engrams to all three resource types. GET list endpoints are now list-only; search always uses POST with a JSON body containing query, limit, detail, and level. - POST /v1/episodes/search — text search over episode content - POST /v1/entities/search — text search over entity names and aliases - Remove ?query= from GET /v1/episodes and GET /v1/entities - Update openapi.yaml, docs/api.md, README.md, CHANGELOG.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
vthunder
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Moves all resource search from `GET /{resource}?query=` to `POST /{resource}/search` with a JSON body, making the pattern consistent across all three resource types.
New endpoints
Changed endpoints
Request body (all three search endpoints)
```json
{"query": "...", "limit": 10, "detail": "full", "level": 0}
```
Motivation
GET request bodies are undefined behavior in HTTP. A query string for semantic search can grow arbitrarily large (future: pre-computed embeddings in the body), so POST is the correct method.
Keeping a consistent pattern across all three resource types — GET = list, POST /search = search — makes the API easier to reason about and extend.
Updated docs
Test plan
🤖 Generated with Claude Code