Add API documentation for graph retrieval, query, and commit history endpoints by gkorland · Pull Request #585 · FalkorDB/code-graph

gkorland · 2026-03-10T08:43:49Z

Migrated from falkordb/code-graph-backend#96

Summary

Adds an API Reference section to the README documenting:

Retrieve a graph (GET /graph_entities)
Send Query (POST /chat)
History change (POST /list_commits, POST /switch_commit)

Resolves #534

Originally authored by @Copilot in falkordb/code-graph-backend#96

Summary by CodeRabbit

Documentation
- Added a "Usage examples" section to the README with concrete curl commands demonstrating how to call the /api/graph_entities (GET), /api/chat (POST), /api/list_commits (POST), and /api/switch_commit (POST) endpoints, including required Authorization: Bearer <YOUR_SECRET_TOKEN> header and example request payloads.

vercel · 2026-03-10T08:43:51Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
code-graph	Error		Mar 10, 2026 8:43am

coderabbitai · 2026-03-10T08:44:02Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: fde76d7e-61b9-408c-aede-b97ed04275bb

📥 Commits

Reviewing files that changed from the base of the PR and between f234233 and d4cb104.

📒 Files selected for processing (1)

README.md

✅ Files skipped from review due to trivial changes (1)

README.md

📝 Walkthrough

Walkthrough

README.md was updated to add a "Usage examples" section containing curl commands and payload examples for the /api/graph_entities (GET), /api/chat (POST), /api/list_commits (POST), and /api/switch_commit (POST) endpoints. This is documentation-only; no code or routing changes.

Changes

Cohort / File(s)	Summary
Documentation `README.md`	Added a "Usage examples" section with concrete curl commands showing `Authorization: Bearer <YOUR_SECRET_TOKEN>` header and request payload examples for `/api/graph_entities` (GET), `/api/chat` (POST), `/api/list_commits` (POST), and `/api/switch_commit` (POST).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰
A little README, tidy and bright,
Four curl commands hopping into the light,
No code to alter, just examples to show,
Tokens and payloads in a neat little row,
Hooray for docs — onward we go! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and clearly describes the main change: adding API documentation for the specified endpoints (graph retrieval, query, and commit history).
Linked Issues check	✅ Passed	All three required APIs are documented: GET /graph_entities (retrieve graph), POST /chat (query), and POST /list_commits and POST /switch_commit (history changes).
Out of Scope Changes check	✅ Passed	Changes are limited to README documentation additions with no modifications to application logic, routing, or other unrelated files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch backend/update-readme-missing-apis

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@README.md`:
- Around line 228-230: The README example includes a literal auth token
("Authorization: OpenSesame") which can encourage reuse and trigger secret
scanners; update the example curl for the graph_entities endpoint to use a
placeholder or environment variable instead (e.g., replace the literal
Authorization header in the curl example for
"http://127.0.0.1:5000/graph_entities?repo=GraphRAG-SDK" with a safe token
reference like ${SECRET_TOKEN} or a named placeholder) so the README no longer
contains a real-looking secret.
- Around line 224-250: Update the curl examples to use the documented
environment variable name SECRET_TOKEN consistently (e.g., replace instances of
<.ENV_SECRET_TOKEN> with ${SECRET_TOKEN}) across the /graph_entities, /chat,
/list_commits, and /switch_commit examples in README.md so the snippets are
copy-pasteable and match the earlier .env example.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 800a6cad-e22f-4258-a9cb-e03cdf23cd8e

📥 Commits

Reviewing files that changed from the base of the PR and between 16feaea and f234233.

📒 Files selected for processing (1)

README.md

README.md

…endpoints Migrated from FalkorDB/code-graph-backend PR #96. Original issue: FalkorDB/code-graph-backend#83 Resolves #534 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

gkorland

Rebased on staging and addressed review comments:

Env var consistency: Replaced all <.ENV_SECRET_TOKEN> with ${SECRET_TOKEN} to match the .env example and be copy-pasteable.
Literal auth token: Replaced Authorization: OpenSesame example with ${SECRET_TOKEN} placeholder to avoid triggering secret scanners.

Copilot

Pull request overview

Adds an API Reference section to README.md to document graph retrieval, chat querying, and commit history endpoints.

Changes:

Added a new “API Reference” section with curl examples for graph retrieval, chat queries, and commit operations.
Added an additional keywords-like line near the end of the README.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-21T21:21:25Z

README.md

+## API Reference
+
+### Retrieve a graph
+
+Fetch graph entities from a repository:
+
+```bash
+curl -X GET "http://127.0.0.1:5000/graph_entities?repo=<REPO_NAME>" -H "Authorization: ${SECRET_TOKEN}"
+```
+
+Example:
+```bash
+curl -X GET "http://127.0.0.1:5000/graph_entities?repo=GraphRAG-SDK" -H "Authorization: ${SECRET_TOKEN}"
+```
+
+### Send Query
+
+Query your code graph using natural language:
+
+```bash
+curl -X POST http://127.0.0.1:5000/chat -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "msg": "<YOUR_QUESTION>"}' -H "Authorization: ${SECRET_TOKEN}"
+```
+
+### History change
+
+List all commits:
+```bash
+curl -X POST http://127.0.0.1:5000/list_commits -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>"}' -H "Authorization: ${SECRET_TOKEN}"
+```
+
+Switch to a specific commit:
+```bash
+curl -X POST http://127.0.0.1:5000/switch_commit -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "commit": "<COMMIT_HASH>"}' -H "Authorization: ${SECRET_TOKEN}"
+```
+


The new API Reference duplicates the existing "## API Endpoints" section above and introduces conflicting/incorrect paths. Consider removing this section or merging it into the existing endpoints table to keep a single source of truth.

Suggested change

## API Reference

### Retrieve a graph

Fetch graph entities from a repository:

```bash

curl -X GET "http://127.0.0.1:5000/graph_entities?repo=<REPO_NAME>" -H "Authorization: ${SECRET_TOKEN}"

```

Example:

```bash

curl -X GET "http://127.0.0.1:5000/graph_entities?repo=GraphRAG-SDK" -H "Authorization: ${SECRET_TOKEN}"

```

### Send Query

Query your code graph using natural language:

```bash

curl -X POST http://127.0.0.1:5000/chat -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "msg": "<YOUR_QUESTION>"}' -H "Authorization: ${SECRET_TOKEN}"

```

### History change

List all commits:

```bash

curl -X POST http://127.0.0.1:5000/list_commits -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>"}' -H "Authorization: ${SECRET_TOKEN}"

```

Switch to a specific commit:

```bash

curl -X POST http://127.0.0.1:5000/switch_commit -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "commit": "<COMMIT_HASH>"}' -H "Authorization: ${SECRET_TOKEN}"

```

Copilot · 2026-03-21T21:21:25Z

README.md

+```bash
+curl -X GET "http://127.0.0.1:5000/graph_entities?repo=<REPO_NAME>" -H "Authorization: ${SECRET_TOKEN}"
+```
+
+Example:
+```bash
+curl -X GET "http://127.0.0.1:5000/graph_entities?repo=GraphRAG-SDK" -H "Authorization: ${SECRET_TOKEN}"
+```


The documented URL is missing the /api prefix. The FastAPI route is /api/graph_entities, so these curl examples will 404 unless updated to use /api/graph_entities.

Copilot · 2026-03-21T21:21:26Z

README.md

+Query your code graph using natural language:
+
+```bash
+curl -X POST http://127.0.0.1:5000/chat -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "msg": "<YOUR_QUESTION>"}' -H "Authorization: ${SECRET_TOKEN}"


The documented URL is missing the /api prefix. The FastAPI route is /api/chat, so this curl example should call /api/chat.

Suggested change

curl -X POST http://127.0.0.1:5000/chat -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "msg": "<YOUR_QUESTION>"}' -H "Authorization: ${SECRET_TOKEN}"

curl -X POST http://127.0.0.1:5000/api/chat -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "msg": "<YOUR_QUESTION>"}' -H "Authorization: ${SECRET_TOKEN}"

Copilot · 2026-03-21T21:21:26Z

README.md

+
+List all commits:
+```bash
+curl -X POST http://127.0.0.1:5000/list_commits -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>"}' -H "Authorization: ${SECRET_TOKEN}"


The documented URL is missing the /api prefix. The FastAPI route is /api/list_commits, so this curl example should call /api/list_commits.

Suggested change

curl -X POST http://127.0.0.1:5000/list_commits -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>"}' -H "Authorization: ${SECRET_TOKEN}"

curl -X POST http://127.0.0.1:5000/api/list_commits -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>"}' -H "Authorization: ${SECRET_TOKEN}"

Copilot · 2026-03-21T21:21:26Z

README.md

+
+Switch to a specific commit:
+```bash
+curl -X POST http://127.0.0.1:5000/switch_commit -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "commit": "<COMMIT_HASH>"}' -H "Authorization: ${SECRET_TOKEN}"


The documented URL is missing the /api prefix. The FastAPI route is /api/switch_commit, so this curl example should call /api/switch_commit.

Suggested change

curl -X POST http://127.0.0.1:5000/switch_commit -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "commit": "<COMMIT_HASH>"}' -H "Authorization: ${SECRET_TOKEN}"

curl -X POST http://127.0.0.1:5000/api/switch_commit -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "commit": "<COMMIT_HASH>"}' -H "Authorization: ${SECRET_TOKEN}"

Copilot · 2026-03-21T21:21:26Z

README.md

+```bash
+curl -X GET "http://127.0.0.1:5000/graph_entities?repo=<REPO_NAME>" -H "Authorization: ${SECRET_TOKEN}"
+```
+
+Example:
+```bash
+curl -X GET "http://127.0.0.1:5000/graph_entities?repo=GraphRAG-SDK" -H "Authorization: ${SECRET_TOKEN}"
+```
+
+### Send Query
+
+Query your code graph using natural language:
+
+```bash
+curl -X POST http://127.0.0.1:5000/chat -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "msg": "<YOUR_QUESTION>"}' -H "Authorization: ${SECRET_TOKEN}"
+```
+
+### History change
+
+List all commits:
+```bash
+curl -X POST http://127.0.0.1:5000/list_commits -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>"}' -H "Authorization: ${SECRET_TOKEN}"
+```
+
+Switch to a specific commit:
+```bash
+curl -X POST http://127.0.0.1:5000/switch_commit -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "commit": "<COMMIT_HASH>"}' -H "Authorization: ${SECRET_TOKEN}"
+```


Auth examples elsewhere in the README use Authorization: Bearer <YOUR_SECRET_TOKEN>. Here the header is shown as Authorization: ${SECRET_TOKEN}; since the backend accepts either raw token or Bearer, consider standardizing these examples to the Bearer form for consistency and clarity.

Copilot · 2026-03-21T21:21:26Z

README.md

+Knowledge Graph, Code Analysis, Code Visualization, Dead Code Analysis, Graph Database
+


This line reads like a list of SEO keywords and isn’t referenced elsewhere in the README. If it’s not intentionally part of the documentation, consider removing it to avoid distracting from the actual content.

Copilot · 2026-03-21T21:21:26Z

README.md

+curl -X POST http://127.0.0.1:5000/chat -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "msg": "<YOUR_QUESTION>"}' -H "Authorization: ${SECRET_TOKEN}"
+```
+
+### History change


Section title "History change" is grammatically unclear. Consider renaming to something like "Commit history" or "History changes" to match the endpoints being documented.

Suggested change

### History change

### Commit history

…p README - Add /api prefix to all curl URLs (graph_entities, chat, list_commits, switch_commit) - Standardize auth header to Bearer format - Rename 'History change' section to 'Commit history' - Remove SEO keywords line Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

gkorland

Addressing remaining unresolved threads:

README.md:262 (missing /api prefix): Fixed in latest commit — all curl URLs now include the /api prefix.

README.md:282 (auth format): Fixed — standardized all examples to Authorization: Bearer <YOUR_SECRET_TOKEN> format.

README.md:283 (duplicate section): Fixed — removed the duplicate API Reference section, keeping only the existing API Endpoints table as single source of truth.

- Remove duplicate 'API Reference' section, merge curl examples into 'API Endpoints' as 'Usage examples' subsection - Standardize auth header to Bearer <YOUR_SECRET_TOKEN> placeholder - Move License section to end of file Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

vercel bot had a problem deploying to Preview March 10, 2026 08:43 Failure

coderabbitai bot reviewed Mar 10, 2026

View reviewed changes

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

Add API documentation for graph retrieval, query, and commit history …

cf62eb5

…endpoints Migrated from FalkorDB/code-graph-backend PR #96. Original issue: FalkorDB/code-graph-backend#83 Resolves #534 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

gkorland force-pushed the backend/update-readme-missing-apis branch from f234233 to cf62eb5 Compare March 21, 2026 10:59

gkorland commented Mar 21, 2026

View reviewed changes

gkorland requested a review from Copilot March 21, 2026 21:19

Copilot started reviewing on behalf of gkorland March 21, 2026 21:19 View session

Copilot AI reviewed Mar 21, 2026

View reviewed changes

gkorland commented Mar 21, 2026

View reviewed changes

	curl -X POST http://127.0.0.1:5000/chat -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "msg": "<YOUR_QUESTION>"}' -H "Authorization: ${SECRET_TOKEN}"
	curl -X POST http://127.0.0.1:5000/api/chat -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "msg": "<YOUR_QUESTION>"}' -H "Authorization: ${SECRET_TOKEN}"

	curl -X POST http://127.0.0.1:5000/list_commits -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>"}' -H "Authorization: ${SECRET_TOKEN}"
	curl -X POST http://127.0.0.1:5000/api/list_commits -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>"}' -H "Authorization: ${SECRET_TOKEN}"

	curl -X POST http://127.0.0.1:5000/switch_commit -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "commit": "<COMMIT_HASH>"}' -H "Authorization: ${SECRET_TOKEN}"
	curl -X POST http://127.0.0.1:5000/api/switch_commit -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "commit": "<COMMIT_HASH>"}' -H "Authorization: ${SECRET_TOKEN}"

		Knowledge Graph, Code Analysis, Code Visualization, Dead Code Analysis, Graph Database

Conversation

gkorland commented Mar 10, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Summary by CodeRabbit

Uh oh!

vercel bot commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

gkorland left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

gkorland left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gkorland commented Mar 10, 2026 •

edited by coderabbitai bot

Loading

vercel bot commented Mar 10, 2026 •

edited

Loading

coderabbitai bot commented Mar 10, 2026 •

edited

Loading