Bridge Application

Bridge REST API

The bridge exposes its API on port 9013 when started as a web service. Paths are relative to the service root — there is no /api prefix.

Authentication

Every endpoint requires the shared token in a header:

X-Auth-Token: <token>

X-Gitlab-Token is accepted as an alternative, so a GitLab webhook can trigger a run directly.

The token is compared against promethist.bridge.secret-token. If that property is blank, all requests are refused with 403 — there is no unauthenticated mode. A wrong token also yields 403.

Starting Runs

All four run endpoints stream their response: one run ID per line, as the runs are started. Read the response as a stream — a run takes minutes, and the connection stays open meanwhile.

Shared parameters:

Parameter Default Meaning

Parameter	Default	Meaning
`variable-group`	`default`	Variable group used to resolve `$VARIABLE` placeholders — see Variable Groups.
`device-delay`	`5000`	Milliseconds to wait between starting devices, so a provider is not hit with all sessions at once.
`parallelism`	`1`	How many runs execute concurrently.

variable-group

default

Variable group used to resolve $VARIABLE placeholders — see Variable Groups.

device-delay

5000

Milliseconds to wait between starting devices, so a provider is not hit with all sessions at once.

parallelism

1

How many runs execute concurrently.

GET or POST /run/test-case/{testCaseId}

Runs every configuration of a test case. This is the endpoint to wire into CI or a scheduler.

curl -N -H "X-Auth-Token: $TOKEN" \
  "https://bridge.example/run/test-case/$TEST_CASE_ID?parallelism=2"

GET /run/configuration?id={configurationId}

Runs a single saved configuration. test-case-id may be passed to associate the resulting run with a test case.

GET /run

Runs an ad-hoc test built entirely from query parameters, with no saved configuration. Parameter names are the hyphenated forms of the run properties: key (required), device-uri (required), engine-url, client-url, relay-url, device-ref, locale, sample-rate, audio-speed, text-only, no-system-prompt, speech-processing, timeout, max-turns-per-session, session-count, device-count, realtime-configuration-id, tester-test-mode, tested-agent-test-mode.

curl -N -H "X-Auth-Token: $TOKEN" \
  "https://bridge.example/run?key=agent:tester\
&device-uri=https%3A%2F%2Feu.promethist.ai%3Fkey%3Dagent%3Aacme-support\
&timeout=300"

POST /run

The same, with a full BridgeProperties JSON body instead of query parameters — the way to start a run with a non-trivial configuration, for example one with device-queries or aggregate-weights.

curl -N -H "X-Auth-Token: $TOKEN" -H "Content-Type: application/json" \
  -d '{
        "key": "agent:tester",
        "device-uri": "https://eu.promethist.ai?key=agent:acme-support",
        "timeout": 300,
        "session-count": 2,
        "aggregate-weights": { "taskCompletion": 0.7, "userEngagement": 0.3 }
      }' \
  "https://bridge.example/run"

Reading Results

GET /run/{runId}

The full BridgeRun document — status, reason, properties used, session ID, final screenshot and evaluation results. See Results and Evaluation.

GET /run/test-case/{testCaseId}/runs

Paginated summaries of the runs of one or more test cases. The projection omits the screenshot and the evaluation payloads, so it is cheap to poll for a dashboard.

Parameter Default Meaning

Parameter	Default	Meaning
`page`	`0`	Page index.
`size`	`50`	Page size.
`test-case-id`	—	Additional test case IDs to include; repeat the parameter.

page

0

Page index.

size

50

Page size.

test-case-id

—

Additional test case IDs to include; repeat the parameter.

GET /run/recording/{runId}.ts

The recorded video of a run, streamed from storage.

Parameter Type Description

Parameter	Type	Description
`runId`	UUID (path)	Run whose recording is requested.

runId

UUID (path)

Run whose recording is requested.

Takes no query parameters. Responds video/mp2t; available when video recording is enabled.

Configurations

Endpoint Effect

Endpoint	Effect
`GET /configuration/{configurationId}`	One configuration.
`GET /configuration?ids=…`	Several configurations by ID.
`POST /configuration`	Create a configuration. The body is a `BridgeConfiguration` — remember the `type` discriminator, see Saved Configurations.
`PUT /configuration/{configurationId}`	Replace a configuration.
`DELETE /configuration/{configurationId}`	Delete a configuration.

GET /configuration/{configurationId}

One configuration.

GET /configuration?ids=…

Several configurations by ID.

POST /configuration

Create a configuration. The body is a BridgeConfiguration — remember the type discriminator, see Saved Configurations.

PUT /configuration/{configurationId}

Replace a configuration.

DELETE /configuration/{configurationId}

Delete a configuration.

Test Cases

Endpoint Effect

Endpoint	Effect
`GET /test-case/{testCaseId}`	One test case.
`POST /test-case`	Create a test case (`name` and `configurationIds`).
`PUT /test-case/{testCaseId}`	Replace a test case.
`DELETE /test-case/{testCaseId}`	Delete a test case.

GET /test-case/{testCaseId}

One test case.

POST /test-case

Create a test case (name and configurationIds).

PUT /test-case/{testCaseId}

Replace a test case.

DELETE /test-case/{testCaseId}

Delete a test case.

Service Endpoints

Endpoint Effect

Endpoint	Effect
`GET /`	Returns `ready to bridge`. Unauthenticated liveness check.
`GET /run/t3st`	Stores a synthetic run, to verify the MongoDB and Elasticsearch wiring of a fresh deployment.

GET /

Returns ready to bridge. Unauthenticated liveness check.

GET /run/t3st

Stores a synthetic run, to verify the MongoDB and Elasticsearch wiring of a fresh deployment.

Scheduled Runs

The deployment can run tests on a schedule without any external system: the bridge Helm chart renders one Kubernetes CronJob per configured job, each calling /run/test-case/{id} or /run/configuration?id={id} with its own variable group and the auth token from a secret. See the bridge chart.