Other AWS Apps Integration

How other AWS applications (e.g. helix-aws services, Lambdas, internal tools) discover and call Helix Flowgraph after CDK deploy.

Helix publishes configuration to SSM Parameter Store — no cross-stack CloudFormation exports required (same pattern as /helix/github-app/*).

---

SSM parameters

Parameter	Purpose
/helix/flowgraph/query-base-url	REST base URL (https://helix-flow.igentify.in)
/helix/flowgraph/cognito-user-pool-id	Cognito pool for /query/* auth
/helix/flowgraph/cognito-client-id	App client id
/helix/flowgraph/artifacts-bucket	Scan artifacts bucket name
/helix/flowgraph/workspace-id	Workspace key (e.g. igentify)
/helix/flowgraph/region	AWS region
/helix/flowgraph/docs-url	This documentation site
/helix/flowgraph/appsync-url	Platform GraphQL URL (scan orchestration only; not documented here)

Read at runtime:

import { SSMClient, GetParametersCommand } from "@aws-sdk/client-ssm";

const names = [
  "/helix/flowgraph/query-base-url",
  "/helix/flowgraph/cognito-client-id",
  "/helix/flowgraph/cognito-user-pool-id",
];
const out = await ssm.send(new GetParametersCommand({ Names: names }));

---

Calling the Query API

1. Load SSM params in your CDK stack or Lambda environment.
2. Obtain a Cognito ID token (user-delegated login or an approved service pattern).
3. Call REST endpoints with X-Helix-Authorization: Bearer <token>.
4. Follow Query REST API for endpoints, graph model, and agent playbooks.

TypeScript client

import { helixQueryJson, loadTechnicalGraphFromQueryResponse } from "@helix/shared";

const config = {
  baseUrl: process.env.HELIX_QUERY_BASE_URL!,
  getIdToken: async () => process.env.HELIX_ID_TOKEN,
};

const { features, scanId } = await helixQueryJson<{ features: unknown[]; scanId: string }>(
  config,
  "/query/features",
);

Package: @helix/shared in the helix-flowgraph monorepo (publish or vendor as your org prefers).

---

CDK in consuming apps

Pass SSM values into Lambda env vars or read them at cold start:

// Example: wire env from SSM in your stack
environment: {
  HELIX_QUERY_BASE_URL: queryBaseUrlParam.stringValue,
  HELIX_COGNITO_CLIENT_ID: clientIdParam.stringValue,
},

Grant the execution role ssm:GetParameters on /helix/flowgraph/* if resolving at runtime.

---

What to query when

Need	Endpoint
Feature list	GET /query/features
One feature subgraph	GET /query/feature?featureId=
One repo	GET /query/repo-graph?repoKey=
Full workspace graph	GET /query/technical-graph
Impact before a code change	POST /query/impact
AI risk / Q&A on an endpoint	GET /query/endpoint-qa?endpointId=

Full catalogue and agent guidance: Query REST API.

---

Scan orchestration

Starting scans and watching progress use the platform GraphQL API (AppSync). The URL is in /helix/flowgraph/appsync-url. That surface is owned by the Helix platform stack — integrate via your platform team if you need programmatic scan triggers; graph reads should use the Query REST API above.