Kit REST API

kit ships a lightweight FastAPI server that exposes most of the same capabilities as the Python API and the MCP server, but over good old HTTP. This page lists every route, its query-parameters and example curl invocations.

The server lives in kit.api.app. Run it directly with:

uvicorn kit.api.app:app --reload

---

1 Opening a repository

POST /repository

Body (JSON):

field	type	required	description
path_or_url	string	yes	Local path or Git URL
ref	string	no	Commit SHA / branch / tag
github_token	string	no	OAuth token for private clones

Return → { "id": "8b1d4f29c7b1" }

The ID is deterministic: sha1(<canonical-path>@<ref>)[:12]. Re-POSTing the same path+ref combination always returns the same ID – so clients can cache it.

Examples:

# Open repository at current state
curl -X POST localhost:8000/repository \
  -d '{"path_or_url": "/my/project"}' \
  -H 'Content-Type: application/json'

# Open repository at specific tag
curl -X POST localhost:8000/repository \
  -d '{"path_or_url": "https://github.com/owner/repo", "ref": "v1.2.3"}' \
  -H 'Content-Type: application/json'

# Open repository at specific commit
curl -X POST localhost:8000/repository \
  -d '{"path_or_url": "https://github.com/owner/repo", "ref": "abc123def456"}' \
  -H 'Content-Type: application/json'

# Open private repository with authentication
curl -X POST localhost:8000/repository \
  -d '{"path_or_url": "https://github.com/owner/private-repo", "github_token": "ghp_xxxx"}' \
  -H 'Content-Type: application/json'

Note If path_or_url is a GitHub URL, the server shells out to git clone. Pass github_token to authenticate when cloning private repositories. The ref parameter allows you to analyze specific versions - useful for historical analysis, release comparisons, or ensuring reproducible results.

2 Navigation

Method & path	Purpose
GET /repository/{id}/file-tree	JSON list of files/dirs
GET /repository/{id}/files/{path}	Raw text response
DELETE /repository/{id}	Evict from registry/LRU

Example:

curl "$KIT_URL/repository/$ID/files/models/user.py"

3 Search

GET /repository/{id}/search?q=<regex>&pattern=*.py

Returns grep-style hits with file & line numbers.

4 Symbols & usages

GET /repository/{id}/symbols?file_path=...&symbol_type=function
GET /repository/{id}/usages?symbol_name=foo&symbol_type=function

/symbols without file_path scans the whole repo (cached).

5 Composite index

GET /repository/{id}/index

Response:

{
  "files": [ ... file-tree items ... ],
  "symbols": { "path/to/file.py": [ {"name": "foo", ...} ] }
}

6 Advanced Capabilities

These endpoints are included in the standard kit installation but may have specific runtime requirements:

Route	Key Runtime Requirement(s)	Notes
/summary	LLM API key (e.g., OPENAI_API_KEY in environment)	Generates code summaries. Returns 400 if key is missing/invalid, 503 if LLM service fails.
/dependencies	None for fetching graph data (Python/Terraform)	Returns dependency graph. graphviz needed only for local visualization helpers, not this endpoint.

7 Git Metadata

GET /repository/{id}/git-info

Returns git repository metadata including current SHA, branch, and remote URL.

Response:

{
  "current_sha": "8cf426abe80f6cd3ab02ffc6fb11b00dd60995c8",
  "current_sha_short": "8cf426a",
  "current_branch": "main",
  "remote_url": "git@github.com:cased/kit.git"
}

Fields will be null if the repository is not a git repository or the information is not available.

Upcoming Features

The following features are currently in development and will be added in future releases:

Planned Feature	Description	Status
/semantic-search	Embedding-based search using vector databases to find semantically similar code chunks	Coming soon
Enhanced symbol analysis	Improved cross-language symbol detection and relationship mapping	Planned

8 Common HTTP Status Codes

• 200 OK: Request succeeded.
• 201 Created: Repository opened successfully.
• 204 No Content: Repository deleted successfully.
• 400 Bad Request: Invalid parameters in the request (e.g., unsupported language for dependencies, missing API key for summaries).
• 404 Not Found: Requested resource (repository, file, symbol) could not be found.
• 500 Internal Server Error: An unexpected error occurred on the server.
• 503 Service Unavailable: An external service required by the handler (e.g., an LLM API) failed or is unavailable.

---

Example session

# 1 Open local repo (deterministic id)
ID=$(curl -sX POST localhost:8000/repository \
     -d '{"path_or_url": "/my/project"}' \
     -H 'Content-Type: application/json' | jq -r .id)

# 1b Open remote repo at specific version
VERSION_ID=$(curl -sX POST localhost:8000/repository \
     -d '{"path_or_url": "https://github.com/owner/repo", "ref": "v1.2.3"}' \
     -H 'Content-Type: application/json' | jq -r .id)

# 2 Check git metadata
curl "localhost:8000/repository/$ID/git-info"

# 3 Find every file that mentions "KeyError"
curl "localhost:8000/repository/$ID/search?q=KeyError"

# 4 Show snippet
curl "localhost:8000/repository/$ID/files/auth/session.py" | sed -n '80,95p'