AST API

Query your codebase structure via REST API. Designed for Claude Code, Gemini CLI, and other AI coding assistants.

Quick Start

Step 1: Get Workspace ID

Required for all API calls:

curl -s 'http://localhost:3033/api/workspaces' | jq '.data.workspaces[0].id'

Step 2: Search for a Symbol

curl 'http://localhost:3033/api/search?q=UserService&workspace=<wsId>&limit=10'

Step 3: Use the Symbol ID

Use the returned symbolId for callers, calls, and impact analysis.

When to Use AST API

Use AST API when:

• User asks "where is X?", "who calls X?"
• You need a file path before editing
• A change may affect multiple files
• Running broad search without a known target

Skip AST API when:

• User provides exact file path
• Task is doc-only or config-only
• Only need literal string search

API Reference

1. Search Symbols

GET /api/search?q=<name>&workspace=<wsId>&limit=10

Response fields:

• symbolId - Use for callers/calls queries
• file - Absolute path
• line - 0-indexed (add 1 for display)
• type - 5=Class, 6=Method, 11=Interface, 12=Function

2. File Dependencies

GET /api/graph/deps?file=src/path/to/file.ts&workspace=<wsId>

Returns: imports (what this file uses) and exports (what it provides)

3. Who Calls This? (Callers)

GET /api/graph/callers?to=<symbolId>&workspace=<wsId>

Find all locations that call or reference this symbol.

4. What Does This Call? (Callees)

GET /api/graph/calls?from=<symbolId>&workspace=<wsId>

Find all symbols that this function/method calls.

5. Impact Analysis

GET /api/impact?symbolId=<id>&depth=2&workspace=<wsId>

Returns all symbols and files affected by changing this symbol. Essential before refactoring.

6. Rebuild Index

POST /api/index/update
Content-Type: application/json
{"workspace":"<wsId>"}

Rebuild index after code changes. Use when search results seem stale.

Common Patterns

Pattern A: Find and Understand a Class

# 1. Find it
curl 'http://localhost:3033/api/search?q=TerminalService&workspace=ws_xxx&limit=1'
# Note the symbolId and file path

# 2. See what it imports/exports
curl 'http://localhost:3033/api/graph/deps?file=src/main/services/TerminalService.ts&workspace=ws_xxx'

# 3. Now read the file with context

Pattern B: Trace Usage

# 1. Find function
curl 'http://localhost:3033/api/search?q=createSession&workspace=ws_xxx&limit=5'
# Pick the right symbolId

# 2. Find all callers
curl 'http://localhost:3033/api/graph/callers?to=<symbolId>&workspace=ws_xxx'

Pattern C: Safe Refactoring

# Before changing a function, check impact
curl 'http://localhost:3033/api/impact?symbolId=<id>&depth=2&workspace=ws_xxx'
# Review impactedFiles before making changes

Decision Flowchart

User asks about code
        |
        v
Is it a "where is X?" question?
    |yes              |no
    v                 v
/api/search      Is it about dependencies?
    |                 |yes         |no
    v                 v            v
Got symbolId?    /api/graph/deps  Is it about call chain?
    |yes                              |yes         |no
    v                                 v            v
Need callers? -----> /api/graph/callers   Use other tools
Need callees? -----> /api/graph/calls
Need impact?  -----> /api/impact

Error Handling

Error	Cause	Action
No workspace found	API not running	Start Termdock app
Empty search results	Symbol not indexed	Try partial name or rebuild index
404 on symbolId	Stale ID after code change	Re-search to get new ID

Key Notes

• Line numbers are 0-indexed - Add 1 when showing to users
• Use relative paths for /api/graph/deps (e.g., src/main/...)
• Symbol IDs are stable until code changes
• API base: http://localhost:3033 (prod) or :3032 (dev)

Installing AST Skill for Claude Code

Open Settings → Skills tab in Termdock
Select Claude Code as target
Click Install on "termdock-ast" skill
Claude Code will now use AST API automatically when relevant