Index and search workspace symbols — functions, classes, variables, and imports — for fast navigation and cross-reference analysis.

Overview

The Symbols API maintains a structured index of named symbols across your workspace. The agent uses it to locate definitions, find all references, and understand cross-file dependencies without reading every file on each turn.

Index Symbols

POST/symbols/index

Parse files and index their named symbols into a workspace. Symbol indexing is language-aware — the parser extracts structured metadata rather than treating code as plain text.

Request body

workspace_idstringbodyrequired

Workspace to index into.

filesarraybodyrequired

Files to parse. Each item has path and content.

Response fields

symbols_indexednumber

Number of symbols indexed.

files_processednumber

Number of files processed.

duration_msnumber

Indexing duration in milliseconds.

POST /symbols/index
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "workspace_id": "my-project",
  "files": [
    {
      "path": "src/lib/auth.ts",
      "content": "export function validateToken(token: string): boolean { ... }"
    }
  ]
}

{
  "symbols_indexed": 128,
  "files_processed": 12,
  "duration_ms": 87
}

Symbol indexing is language-aware. The parser extracts structured metadata (name, kind, signature, location) rather than treating code as plain text.

Search Symbols

GET/symbols/search

Search indexed symbols by name substring or pattern, optionally filtered by type.

Query parameters

qstringqueryrequired

Search query (name substring or pattern).

typestringquerydefault: all

Filter by symbol type: function, class, variable, import.

limitnumberquerydefault: 20

Maximum results to return.

workspace_idstringquery

Scope search to a specific workspace.

Response fields

symbolsarray

Matching symbols. Each includes name, kind, path, start_line, end_line, signature, and exported.

totalnumber

Total number of matches.

query_msnumber

Query duration in milliseconds.

GET /symbols/search?q=validateToken&type=function&limit=20
Authorization: Bearer YOUR_API_KEY

{
  "symbols": [
    {
      "name": "validateToken",
      "kind": "function",
      "path": "src/lib/auth.ts",
      "start_line": 14,
      "end_line": 28,
      "signature": "function validateToken(token: string): boolean",
      "exported": true
    }
  ],
  "total": 1,
  "query_ms": 4
}

Symbol Kinds

Kind	Examples
`function`	Functions, methods, arrow functions, lambdas
`class`	Classes, abstract classes, interfaces, structs
`variable`	Constants, let/var declarations, module-level bindings
`import`	Import statements, require calls, use declarations

Find References

GET/symbols/refs

Find all references to a symbol by exact name, along with its definition.

Query parameters

namestringqueryrequired

Exact symbol name to find references for.

workspace_idstringquery

Scope to a specific workspace.

Response fields

symbolstring

The symbol name that was searched.

definitionobject

The symbol definition, including path and start_line.

referencesarray

Reference sites. Each includes path, line, and context.

reference_countnumber

Total number of references found.

GET /symbols/refs?name=validateToken&workspace_id=my-project
Authorization: Bearer YOUR_API_KEY

{
  "symbol": "validateToken",
  "definition": {
    "path": "src/lib/auth.ts",
    "start_line": 14
  },
  "references": [
    { "path": "src/api/session.ts", "line": 42, "context": "if (!validateToken(req.token)) {" },
    { "path": "src/middleware.ts", "line": 8, "context": "const valid = validateToken(token);" }
  ],
  "reference_count": 2
}

Database Stats

GET/symbols/stats

Return symbol index statistics for a workspace.

Query parameters

workspace_idstringquery

Workspace to report on.

Response fields

workspace_idstring

The workspace identifier.

total_symbolsnumber

Total number of indexed symbols.

by_kindobject

Counts per symbol kind: function, class, variable, import.

files_indexednumber

Number of files indexed.

last_indexedstring

ISO-8601 timestamp of the last indexing operation.

GET /symbols/stats?workspace_id=my-project
Authorization: Bearer YOUR_API_KEY

{
  "workspace_id": "my-project",
  "total_symbols": 2847,
  "by_kind": {
    "function": 1203,
    "class": 284,
    "variable": 1190,
    "import": 170
  },
  "files_indexed": 94,
  "last_indexed": "2026-03-21T14:32:00Z"
}

Use /symbols/refs to safely understand the blast radius before the agent renames or refactors a symbol. A symbol with many references warrants a careful, multi-file edit approach.