API Reference

Authentication

All API requests require authentication. Codegraphs supports two methods:

Method	Header	Use Case
API Key	Authorization: Bearer <key>	Service-to-service, CI/CD pipelines
JWT (RS256)	Authorization: Bearer <token>	User sessions (via Gateway)

# Using an API key
curl -H "Authorization: Bearer dvn-api-key-xxxx" \
     https://api.codegraphs.com/api/search?q=CUSTOMER

Search API

GET /api/search

Parameter	Type	Description
q	string	Search query (required)
schema	string	Target schema name
ext	string	Filter by extension
dir	string	Filter by directory
page	integer	Page number (default 0)
page_size	integer	Results per page (default 20, max 100)

GET /api/search?q=CUSTOMER&ext=cbl&schema=hokuriku&page_size=50

Graph API

GET /api/module-path-graph?schema=&from_fid=&to_fid=&max_depth=

Finds the dependency path between two files (default depth 15, max 20). Returns JSON: {"nodes": [...], "edges": [...], "found": bool, "path_length": int}.

GET /api/module-graph?schema=&fid=&dep=&direction=

Renders an interactive call-graph viewer centered on a file, up to dep hops (default 2, max 10) in direction (both / caller / callee).

GET /api/graph?schema=&fid=

Returns the pre-rendered call/procedure graph image for a file (PNG/SVG), generating it on demand for COBOL and JCL if not already cached.

Index API

POST /api/schema/reindex

Body: {"schema": "name", "rebuild": false}. Queues a reindex job for the schema (rate-limited to 10/min per organization; rejected with 400 if a job is already running for that schema). Returns immediately: {"ok": true, "schema": ..., "job_id": ...} — indexing runs asynchronously.

GET /api/schema/reindex/status?schema=

Returns {"status": "queued"|"running"|"done"|"error"|"not_found", "log": "...", "elapsed": <seconds>}.

Admin API

Endpoint	Method	Description
/api/admin/orgs	GET	List all organizations (owner only)
/api/admin/users	GET	List users in current tenant
/api/audit/logs	GET	Query audit log entries
/api/audit/summary	GET	Audit log summary statistics
/api/internal/warmup	POST	Preload schema caches after restart

Rate Limits

All authenticated requests share a flat rate limit of 120 requests/minute per organization, enforced at the Search API layer. Organization owners are exempt. Exceeding the limit returns HTTP 429.

Webhooks

Codegraphs can receive push webhooks from GitHub or GitLab to automatically pull and reindex a schema when your repository changes.

GET /api/git/webhook-secret/{schema}

Generates (or returns) the signing secret and webhook URL for a schema (admin only).

POST /api/git/webhook/{schema}

Register this URL in your repository's webhook settings. GitHub requests are verified via X-Hub-Signature-256; GitLab via X-Gitlab-Token. On success, queues a pull + reindex job and returns {"ok": true, "queued": true, "job_id": ...}.