# Helm API

> Entity-driven workflow platform. Query and relate data by entity type with
> flexible schemas, define workflows/jobs/app-specs, and drive bridge apps.
> REST + GraphQL.

- Base URL (default/staging): https://api.staging.bridge-labs-dev.com
- Full OpenAPI spec (machine-readable): /spec/helm-api-general.json (also .yaml)
- Interactive reference: /openapi/ — GraphQL playground: /graphql/

## Authentication
HTTP Basic with a Personal Access Token (PAT):
`Authorization: Basic base64(client_id:client_secret)`. Requests are
tenant-scoped by the token; row-level security is enforced server-side.

## Response & error envelope
Success responses return a JSON body. Errors always use:
`{ "error": { "status": <int>, "code": "<STABLE_CODE>", "message": "<text>", "details": {} } }`
The HTTP status is authoritative (`status` mirrors it). Common codes: 400 bad
request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict
(duplicate identifier_key / cardinality violation), 422 validation error.

## Pagination
Offset (`page`/`limit`) on list + `POST /entity/query`. Keyset (`cursor` →
`next_cursor`) on `POST /entity/query` for stable iteration of large sets.
`include_count` + `count_strategy` (exact|estimate|capped) for totals.

## Conventions
snake_case JSON fields. UUIDs for ids. All request/response shapes are in the
OpenAPI spec; operations carry an advisory `x-permission` (resource, action).

## Key public routes
- Entities: `GET|POST /entity/entities`, `GET|PUT|PATCH|DELETE /entity/entities/{id}`,
  `POST /entity/entities/upsert`, `POST /entity/query`, `POST /entity/query-graph`,
  `GET /entity/graphql/schema`, `POST /entity/graphql`
- Entity types: `/entity/entity-types` — Relationship rules:
  `/entity/relationship-rules` — Relationships: `/entity/relationships`
- Schemas: `/schema/schemas`, `/schema/validate`
- Definitions: `/definition/workflows`, `/definition/jobs`, `/definition/specs`
- Workflow activation + runs: `/workflows/{id}/{activate,config,triggers}`,
  `/workflows/runs`, `/workflows/schedules` (the `/engine/*` prefix is a
  deprecated alias)
- Apps (bridge): `POST /apps/run`, `/apps/{specId}/{config,integrations,principals}`
- Access (tenant admin): `/access/{users,roles,policies,grants,api-tokens,manifests}`
- Auth: `POST /auth/token`, `/auth/tokens/api`

For exhaustive parameters, schemas, and examples, read /spec/helm-api-general.json.