API Reference

The ArchGraph REST API is available at api.archgraph.dev.

Authentication

All API requests require authentication via one of:

• API Key: Authorization: Bearer ag_... header
• Clerk JWT: For web dashboard sessions

Plan Gating

Endpoints are tagged with the minimum plan tier required:

• Free — included with the free plan
• Pro — requires the Pro plan or higher
• Enterprise — requires the self-hosted Enterprise deployment

Endpoints

Tools — Free (8)

Method	Endpoint	Description
POST	/api/tools/search	Search code nodes by name, type, or rich query syntax
POST	/api/tools/stats	Graph statistics (node counts by type)
POST	/api/tools/impact	Blast radius analysis (upstream/downstream callers)
POST	/api/tools/context	Node neighborhood: callers, callees, file, security flags
POST	/api/tools/source	Source code body for a symbol
POST	/api/tools/search_calls	Search caller/callee relationships (CALLS edges)
POST	/api/tools/detect_changes	Recent file changes with downstream impact
POST	/api/tools/import_tree	Import/dependency graph between modules; circular import detection

Tools — Pro (12)

Method	Endpoint	Description
POST	/api/tools/query	Read-only Cypher queries against the code graph
POST	/api/tools/find_vulnerabilities	CVE/GHSA matches on dependencies
POST	/api/tools/taint_paths	Taint propagation source→sink chains
POST	/api/tools/data_flow	Data flow tracking through assignments and calls
POST	/api/tools/clusters	Functional clusters (community detection) with cohesion scores
POST	/api/tools/churn	File modification hotspots from git history
POST	/api/tools/cfg	Control flow graph (basic blocks + branches) for a function
POST	/api/tools/processes	Execution flow traces from entry points
POST	/api/tools/diff_summary	Compare current repo state against stored graph
POST	/api/tools/cross_repo_impact	Cross-repo blast radius — accepts workspace_id
POST	/api/tools/cross_repo_taint	Cross-repo taint flow — accepts workspace_id
POST	/api/tools/dependency_graph	Repo-level dependency graph for a workspace

Workspaces — Pro

Workspaces group repositories for cross-repo analysis. The workspace_id returned here is passed to the cross_repo_* and dependency_graph tools.

Method	Endpoint	Description
POST	/api/workspaces	Create a workspace
GET	/api/workspaces	List workspaces
GET	/api/workspaces/:id	Workspace detail with member repos
PUT	/api/workspaces/:id	Update name/description
DELETE	/api/workspaces/:id	Delete a workspace
POST	/api/workspaces/:id/repos	Add a repo to the workspace
DELETE	/api/workspaces/:id/repos/:repo_id	Remove a repo from the workspace
POST	/api/workspaces/:id/analyze	Trigger fresh extraction across all member repos
GET	/api/workspaces/:id/dependencies	Cross-repo dependency graph

Repositories

Method	Endpoint	Description
GET	/api/repos	List connected repos
POST	/api/repos	Connect a repo
DELETE	/api/repos/:id	Remove a repo
POST	/api/repos/:id/extract	Trigger extraction (see below)
POST	/api/repos/:id/webhook	Retry webhook registration
GET	/api/repos/:id/status	Extraction status
GET	/api/repos/public	Browse public catalog

POST /api/repos/:id/extract

Enqueues a fresh extraction. Returns 202 Accepted with a job id; poll GET /api/repos/:id/status (or GET /api/repos) until status="ready".

Request body (all fields optional — sane defaults if omitted or body absent):

Field	Type	Default	Notes
include_body	bool	true	Persist function/class source bodies on graph nodes
include_git	bool	true	Run git-history pipeline (churn, blame)
include_scip	bool | null	true	SCIP precise call resolution. On for every plan — turning this off cripples cross-file call accuracy
include_cve	bool | null	true on Pro/Enterprise, ignored on Free	CVE/GHSA dependency matching. Free callers cannot force-enable
enable_joern_taint	bool | null	false	Joern-backed inter-procedural taint. Pro/Enterprise only — silently zeroed for Free regardless of value. JVM cost ~1–3 min/run, so opt-in even on paid tiers
force_full	bool | null	false	Wipe the stored manifest before enqueueing → forces a full (non-incremental) rebuild. Use after a core-logic change so clustering / process tracing / symbol index see the entire call graph instead of the modified-file delta

Plan rules:

• Free — Tree-sitter parse + SCIP + git history. CVE and Joern taint are unavailable.
• Pro / Enterprise — adds CVE matching by default and exposes Joern taint as an opt-in.

Response (202) — ExtractionTriggerResult:

{
  "job_id": "uuid",
  "status": "pending",
  "coalesced": false,
  "queued_retrigger": false,
  "triggered_by": "manual"
}

coalesced / queued_retrigger are surfaced for symmetry with the webhook fan-out path; manual triggers always carry triggered_by="manual" and coalesced=false because the route's 409 short-circuit (below) pre-empts the coalesce branch.

409 Conflict — when an extraction is already pending or extracting for this repo:

{
  "detail": {
    "error": "extraction_in_progress",
    "message": "An extraction is already running for this repo.",
    "job_id": "uuid"
  }
}

The web dashboard treats this as a non-error: it surfaces the existing job_id so the user can keep watching the in-flight run. Webhook-driven triggers do not hit this path — they coalesce silently, queue a follow-up via pending_re_extract, and return coalesced=true.

Code Hosts

OAuth-backed integrations for GitHub, GitLab, Bitbucket, and Azure DevOps. Used to discover and connect repositories from third-party hosts.

Method	Endpoint	Description
GET	/api/code-hosts	List configured code hosts
POST	/api/code-hosts	Add a code host connection
DELETE	/api/code-hosts/:id	Remove a code host connection
GET	/api/code-hosts/providers	List supported providers

Webhooks

Inbound receivers for repository events from external code hosts. These endpoints are called by GitHub/GitLab/Bitbucket/Azure — not invoked directly by clients.

Method	Endpoint	Description
POST	/api/webhooks/github	GitHub webhook receiver
POST	/api/webhooks/gitlab	GitLab webhook receiver
POST	/api/webhooks/bitbucket	Bitbucket webhook receiver
POST	/api/webhooks/azure	Azure DevOps webhook receiver

Audit Log — Enterprise

Method	Endpoint	Description
GET	/api/audit	Query the tenant audit log (filterable by action, date range)

API Keys

Method	Endpoint	Description
GET	/api/keys	List API keys
POST	/api/keys	Create API key
POST	/api/keys/:id/rotate	Rotate an API key (old key valid for 24h grace period)
DELETE	/api/keys/:id	Revoke API key

Account

Method	Endpoint	Description
GET	/api/auth/me	Current user profile + plan + tenant
DELETE	/api/auth/me	Delete account (GDPR — removes Postgres, Neo4j, Zoekt data)

Health

Method	Endpoint	Description
GET	/health	Service health check