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 1 commit into
base: staging
Choose a base branch
from
Open

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
35 changes: 35 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,3 +214,38 @@ Have questions or feedback? Reach out via:
If you find this repository helpful, please consider giving it a star!

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

## 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: <.ENV_SECRET_TOKEN>"
```

Example:
```bash
curl -X GET "http://127.0.0.1:5000/graph_entities?repo=GraphRAG-SDK" -H "Authorization: OpenSesame"
Comment on lines +228 to +230
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 10, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Avoid documenting a literal auth token in the example.

Using Authorization: OpenSesame encourages copying a shared static token pattern into local setups and will keep triggering secret scanners on the README. Prefer the same placeholder or shell variable form you use elsewhere instead.

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

<!-- suggestion_start -->

<details>
<summary>📝 Committable suggestion</summary>

> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

```suggestion
Example:
🧰 Tools
🪛 Gitleaks (8.30.0)

[high] 225-230: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.

(curl-auth-header)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 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.

```

### 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: <.ENV_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: <.ENV_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: <.ENV_SECRET_TOKEN>"
Comment on lines +224 to +250
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 10, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Use the documented env var name consistently in the curl snippets.

<.ENV_SECRET_TOKEN> does not match the earlier .env example, which defines SECRET_TOKEN. Using ${SECRET_TOKEN} here would be clearer and copy-pasteable.

Suggested doc update 
-curl -X GET "http://127.0.0.1:5000/graph_entities?repo=<REPO_NAME>" -H "Authorization: <.ENV_SECRET_TOKEN>"
+curl -X GET "http://127.0.0.1:5000/graph_entities?repo=<REPO_NAME>" -H "Authorization: ${SECRET_TOKEN}"
-curl -X POST http://127.0.0.1:5000/chat -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "msg": "<YOUR_QUESTION>"}' -H "Authorization: <.ENV_SECRET_TOKEN>"
+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/list_commits -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>"}' -H "Authorization: <.ENV_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/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/switch_commit -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "commit": "<COMMIT_HASH>"}' -H "Authorization: ${SECRET_TOKEN}"
🧰 Tools
🪛 Gitleaks (8.30.0)

[high] 225-230: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.

(curl-auth-header)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 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.

```
Loading