Skip to content

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

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
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4a5bc02
Initial plan
Copilot Nov 2, 2025
405d022
Add missing API documentation to README
Copilot Nov 2, 2025
9016602
Fix flake8 error: remove unnecessary global declaration
Copilot Nov 2, 2025
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
97 changes: 97 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,103 @@ For example:
curl -X POST http://127.0.0.1:5000/analyze_folder -H "Content-Type: application/json" -d '{"path": "/Users/roilipman/Dev/GraphRAG-SDK", "ignore": ["./.github", "./build"]}' -H "Authorization: OpenSesame"
```

## 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>"
```

For example:

```bash
curl -X GET "http://127.0.0.1:5000/graph_entities?repo=GraphRAG-SDK" -H "Authorization: OpenSesame"
```

Response:
```json
{
"status": "success",
"entities": {
"nodes": [...],
"edges": [...]
}
}
```

### 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>"
```

For example:

```bash
curl -X POST http://127.0.0.1:5000/chat -H "Content-Type: application/json" -d '{"repo": "GraphRAG-SDK", "msg": "What are the main classes in this project?"}' -H "Authorization: OpenSesame"
```

Response:
```json
{
"status": "success",
"response": "The main classes in this project are..."
}
```

### History change

List all commits in a repository:

```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>"
```

For example:

```bash
curl -X POST http://127.0.0.1:5000/list_commits -H "Content-Type: application/json" -d '{"repo": "GraphRAG-SDK"}' -H "Authorization: OpenSesame"
```

Response:
```json
{
"status": "success",
"commits": [
{
"hash": "abc123",
"date": 1234567890,
"author": "John Doe",
"message": "Initial commit"
}
]
}
```

Switch repository 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>"
```

For example:

```bash
curl -X POST http://127.0.0.1:5000/switch_commit -H "Content-Type: application/json" -d '{"repo": "GraphRAG-SDK", "commit": "abc123"}' -H "Authorization: OpenSesame"
```

Response:
```json
{
"status": "success"
}
```
Comment on lines +44 to +139
Copy link
Contributor

@coderabbitai coderabbitai bot Nov 2, 2025

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

Hardcoded authorization token in curl examples presents security risk.

Gitleaks flagged 4 instances of authorization tokens in the curl command examples (lines 51-57, 76-82, 98-104, 125-131). While "OpenSesame" is clearly a placeholder, including literal token values in documentation examples—even placeholders—normalizes a risky copy-paste pattern that could lead developers to accidentally commit real secrets.

Recommendation: Add a prominent note before the examples explaining that developers should never include literal tokens in curl commands, or refactor the examples to use environment variable references instead:

+> **⚠️ Security Note:** Never include actual authorization tokens in curl commands or documentation. Always use environment variables or secrets management.

 ### 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>"
+curl -X GET "http://127.0.0.1:5000/graph_entities?repo=<REPO_NAME>" -H "Authorization: $AUTH_TOKEN"

For example:

-curl -X GET "http://127.0.0.1:5000/graph_entities?repo=GraphRAG-SDK" -H "Authorization: OpenSesame"
+# Set AUTH_TOKEN environment variable: export AUTH_TOKEN="your_token_here"
+curl -X GET "http://127.0.0.1:5000/graph_entities?repo=GraphRAG-SDK" -H "Authorization: $AUTH_TOKEN"

Apply the same refactoring pattern to the POST /chat (lines 76-82), POST /list_commits (lines 98-104), and POST /switch_commit (lines 125-131) examples.

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 Gitleaks (8.28.0)</summary>

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

(curl-auth-header)

---

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

(curl-auth-header)

---

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

(curl-auth-header)

---

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

(curl-auth-header)

</details>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

In README.md around lines 44 to 139, replace the hardcoded "OpenSesame"
Authorization examples and add a short warning about never including literal
tokens: add one-line note above the examples telling users to never paste real
tokens and to use an environment variable (e.g., AUTH_TOKEN). For each curl
example at lines 51-57, 76-82, 98-104, and 125-131 swap the literal
Authorization value with the environment variable reference ($AUTH_TOKEN) and
include an example export command (export AUTH_TOKEN="your_token_here")
immediately before the concrete example lines so readers set the env var rather
than hardcoding secrets.


</details>

<!-- This is an auto-generated comment by CodeRabbit -->


## Working with your graph

Once the source code analysis completes your FalkorDB DB will be populated with
Expand Down
2 changes: 0 additions & 2 deletions api/llm.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -235,8 +235,6 @@ def _define_ontology() -> Ontology:
ontology = _define_ontology()

def _create_kg_agent(repo_name: str):
global ontology

model_name = os.getenv('MODEL_NAME', 'gemini/gemini-2.0-flash')

model = LiteModel(model_name)
Expand Down