HitL API

Backend API for Human in the Loop. This service handles session, agent, migration, task, and browser-facing API behavior used by the hitl frontend and related platform integrations.

Local Development

Requirements:

• Node.js 20+
• npm 10+
• Docker Desktop or another local PostgreSQL setup
• OR_NPM_TOKEN for private dependencies
• deploy-platform installed locally so config can be generated

1. Install dependencies

npm install

2. Start PostgreSQL

Example with Docker:

docker pull postgres
docker run --name postgresql-local -e POSTGRES_USER=hitl-app -e POSTGRES_PASSWORD=mysecretpassword -e POSTGRES_DB=hitl-app-db -p 5432:5432 -d postgres

3. Create .env

APP_DEV_PORT=8080
DB_USER=hitl-app
DB_PASSWORD=mysecretpassword
DB_HOST=localhost
DB_PORT=5432
DB_NAME=hitl-app-db
SCHEDULED_TASKS_SWITCH='{"ARCHIVE_SESSION_EVENTS":true,"CLEAN_UP_LISTENERS":true,"CLEAN_UP_SESSIONS":true,"ADD_EVENTS_TO_ARCHIVE":true,"ADD_MEMBERS_TO_ARCHIVE":true,"CLEAN_UP_CONTACTLESS_SESSIONS":true,"FIX_EXPIRED_AGENT_STATUSES":true,"DELETE_EXPIRED_SESSIONS":true,"LONG_EXPIRE_DAYS":7,"SHORT_EXPIRE_DAYS":1}'

4. Generate deploy config

or get-config --branch local --client development --env qa --feature master --project hitl-api --service hitl_api.config --service-or-eval service > config.json

5. Start the server

npm start

6. Run migrations

curl --location --request POST 'http://localhost:8080/api/v1/migrations' --header 'Authorization: user'

7. Run tests

npm test

Main Areas

• src/api/ and src/api-express/: serverless and express entrypoints
• src/api-common/: shared middleware, auth, logging, validation, and versions endpoints
• src/api-express/migrations/: SQL and migration management
• tests/: Jest-based backend coverage

Shared Parent Domain Aliases

hitl-api participates in the shared-parent-domain alias flow as a supporting API for branded hitl deployments.

That means:

• browser-facing host trust should be explicit
• CORS behavior should be driven by configured trusted hosts
• deploy-platform config must stay aligned with the UI aliases and allowed hosts used by the frontend

Read the full platform behavior here: deploy-platform shared-parent-domain alias documentation