Skip to content

Add API documentation for graph retrieval, query, and commit history endpoints #585

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gkorland wants to merge 3 commits into
base: staging
Choose a base branch
from
Open

Add API documentation for graph retrieval, query, and commit history endpoints #585

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cf62eb5
Add API documentation for graph retrieval, query, and commit history …
gkorland Mar 10, 2026
625f87d
fix(docs): address review — add /api prefix, fix auth header, clean u…
gkorland Mar 21, 2026
d4cb104
fix(docs): merge duplicate API sections, standardize auth format
gkorland Mar 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -246,4 +246,41 @@ A C analyzer exists in the source tree, but it is commented out and is not curre

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

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

Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
## 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}"
```
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.

### 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}"
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
```

### History change
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copilot uses AI. Check for mistakes.

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}"
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
```

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}"
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
```
Comment on lines +248 to +275
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.

Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
Copyright FalkorDB Ltd. 2025
Loading