Helix API

Give every agent a living graph.

The same Engineering Graph the workspace uses is available over HTTP. API Ask reconstructs an answer from that graph. The workspace Ask path may also use a language model when you are signed in. Create a key in Settings.

A glass API surface showing a living cyan-violet graph

01 / Auth

One key. Shown once.

Send the key as a Bearer token. Signed-in sessions work without a key for interactive use. Keys are hashed at rest.

Authorization: Bearer hx_live_…

02 / Endpoints

The graph, over HTTP.

Pass ?sample=1 to read the demo graph, or ?repository=owner/name for a saved index.

GET

/api/v1/graph

Serialized Engineering Graph: nodes, edges, and stats.

GET

/api/v1/insights

Pulse: hot files, silos, experts, coupling, architecture.

GET

/api/v1/search?q=

Search people, files, directories, and pull requests.

POST

/api/v1/ask

Ask a natural-language question. Cited answer from the graph.

GET

/api/v1/review?number=

Helix Review: readiness, missing evidence, and recommended actions.

POST

/api/v1/review

Same as GET. Pass { number, post: true } to update the pull-request comment.

GET

/api/v1/usage

Remaining quota for the calling key.

03 / Ask

A question. Citations. Follow-ups.

API Ask is deterministic graph QA. It does not call a language model. Response includes answer, citations, and followUps. GET with ?q= is accepted for the same route. Server-to-server only. No CORS.

curl -s /api/v1/ask \
  -H "Authorization: Bearer hx_live_…" \
  -H "Content-Type: application/json" \
  -d '{"question":"Who owns src?"}'

04 / Helix Review

Ship, review, or hold: from history.

Evaluates ship readiness from change impact, ownership, GitHub checks, operational paths, and evidence coverage. Helix fills a review template from the live PR and indexed history, then keeps one marked PR comment updated as evidence changes. Auto-review is on once a GitHub token is saved; turn it off in Settings.

curl -s "/api/v1/review?number=41&sample=1" \
  -H "Authorization: Bearer hx_live_…"

POST with { "number": 41, "post": true } updates one marked Helix comment on the pull request and publishes the helix/readiness commit status. The workspace shows the same report. The sample graph cannot post.

05 / Webhooks

A review on every pull request.

Each workspace has a unique webhook URL and secret in Settings. Add a repository webhook for pull request events, content type JSON, using that secret. Helix handles ping, then opened, synchronize, reopened, and ready_for_review, skipping drafts and closed PRs. It inspects the PR, fills the template, and updates the existing Helix Review comment.

POST /api/hooks/{id}
X-Hub-Signature-256: sha256=…
X-GitHub-Event: pull_request

Invalid signatures return 401. Unknown ids return 404. Budget, missing graph, and disabled auto-review acknowledge the delivery and skip the review. GitHub must be able to reach the deployed Helix workspace.

06 / Graph model

Directories exist so orgs can see the map.

Nodes and edges are the product. Not a bag of files. A living memory of how the software evolved.

Nodes

repositoryThe indexed GitHub repo.

directoryA folder reconstructed from file paths. The unit orgs talk in.

fileA path touched in the indexed window.

pull_requestA merged change. Evidence, not a ticket.

personAn author or reviewer from merge history.

patternDNA a loop encoded back onto the graph.

agentA watching loop: Silo, Coupling, Expertise, DNA, Memory.

Relationships

BELONGS_TOPR → repository.

AUTHOREDPerson → PR.

REVIEWEDPerson → PR.

MODIFIEDPR → file.

CONTAINSRepo or directory → nested directory or file.

COUPLEDFile ↔ file that repeatedly share PRs.

MENTIONSPR → PR referenced as #N.

OWNSPerson → file with majority authorship.

TOUCHEDPerson → directory they keep changing.

LEARNEDAgent or pattern → the node it encoded.

WATCHESAgent → the files or people it tracks.

ENCODEDPattern → the evidence that produced it.

07 / Budgets

Evidence as a budget. Not a vanity cap.

Burst is per minute; volume is per UTC day. Over quota returns 429. Upgrade on the pricing page.

Plan	Per day	Per minute	Ask Helix	Reviews / day
Explorer	100	10	5	10
Team	2,000	60	Unlimited	200
Scale	20,000	300	Unlimited	2,000

401

Missing or unknown key.

404

No saved graph for that repository, or unknown path.

429

Daily or per-minute budget exceeded. Headers: X-RateLimit-Limit, Remaining, Reset.

Git

records what changed.

Helix

remembers why.

Give an agent the graph. Keep the citations.