Receive results
A bridge is a small program that pulls your account's workflow results over HTTPS and writes them into your system. It needs no code from us: any language with an HTTP client and a JSON parser will do. This page is the loop it runs. The field tables are generated from API contract 1.5.1, the same files the connectors repository commits under contract/; Results protocol explains the payload in depth.
Think of it as a newspaper subscription: you say who you are once (check in), read every issue after the last one you finished (the cursor), do what an approved notice asks once, never twice (act exactly once), and tell the publisher what you did with each issue (report).
your bridge Constellation API
─────────── ─────────────────
start ── POST /predictions/feed/checkin ──────────▶ who you are, what you may write
first start ── GET /predictions/feed?from=latest ─▶ next: where to start
loop:
GET /predictions/feed?after=<cursor> ───────────▶ entries: finished runs, oldest first
apply each run, act on new approvals (once, before deadline)
POST /predictions/feed/deliveries ──────────────▶ what you wrote for that run
save the run's cursor, then the next
Every call takes the header x-api-key with a live key that has predictions:read. Bodies are JSON. Answer a 5xx or a dropped connection by retrying; the status codes a bridge acts on are in the protocol reference.
1. Check in
POST /predictions/feed/checkin on start, and again every few minutes: Constellation shows a connection that stopped checking in as stopped. It answers 204. A bridge for your own system sends system: "custom" and a manifest whose name is its consumer; Your own connector shows one.
| Field | Type | Required | The contract allows |
|---|---|---|---|
bridge_version | string | No | at most 40 characters |
can | Grants | No | |
consumer | string | Yes | matches `^[a-z0-9][a-z0-9-]{0,62}$` |
manifest | ConnectorManifest | No | |
mapping_versions | array of integer | No | at most 10 items |
system | "yamcs" or "lattice" or "cosmos" or "custom" | Yes | |
system_version | string | No | at most 40 characters |
target | string | No | at most 200 characters |
widget | Installed | No |
The manifest:
| Field | Type | Required | The contract allows |
|---|---|---|---|
description | string | No | at most 300 characters |
name | string | Yes | matches `^[a-z0-9][a-z0-9-]{0,62}$` |
settings | object | No | at most 20 entries |
title | string | Yes | 1 to 80 characters |
Each of its settings:
| Field | Type | Required | The contract allows |
|---|---|---|---|
default | boolean or integer or number or string | Yes | |
description | string | No | at most 300 characters |
max_length | integer | No | 1 to 2000 |
maximum | number | No | |
minimum | number | No | |
options | array of string | No | at most 20 items |
title | string | Yes | 1 to 80 characters |
type | "number" or "integer" or "boolean" or "string" or "enum" | Yes |
2. Read the feed from your cursor
GET /predictions/feed answers {"entries": [{"cursor", "otlp"}], "next", "oldest"}: the finished runs after after, oldest first. Always send consumer, your connection's name, so each entry holds only what is addressed to you and Constellation records how far you have read.
| Field | Type | Required | The contract allows |
|---|---|---|---|
after | string | No | |
limit | integer | No | 1 to 20; default 20 |
consumer | string | No | matches `^[a-z0-9][a-z0-9-]{0,62}$` |
page_records | integer | No | 1 to 5000 |
cursor | string | No | 1 to 128 characters |
page | integer | No | at least 0; default 0 |
from | "latest" | No |
- First start. With no saved cursor, call it with
from=latest. It answers no entries and anextjust before the newest run that has something for you: read on from there, so you apply the newest run and never the week of history before it. - Resume. Save each run's
cursoronce you have applied and reported it, somewhere that survives a restart (a volume, or your system), and send it asafter. A cursor sorts as a string in the order runs finished; treat it as opaque otherwise. Never move past a run you failed to apply. - Once each. The feed can deliver a run again, such as after a failover. Skip an entry whose cursor is not after the one you saved, and read on through it to the newest.
- Gaps.
oldestis the oldest cursor the feed still holds (7 days). A saved cursor older than it means runs expired while the bridge was off: log it and read on. - Large runs. Add
page_records, then fetch the rest of an entry withcursorandpageuntil there is nonext_page. Apply a run whole, never a page of it.
Each entry's otlp is an OTLP/JSON logs document: a resource per output, with the run in constellation.run_id, and a log record per item whose body is the item. Read only the item shape (constellation.schema) you were built for; skip and log a run in any other. The item:
| Field | Type | Required | The contract allows |
|---|---|---|---|
action | Action | No | |
action_id | string | No | A held action, the same on every run that suggests the same verb on the same entity to the same target. |
action_status | string | No | known values: pending, approved, rejected. Where a held action stands. Known values: pending, approved, rejected. Only approved may be acted on: any other or unknown value is held. |
decision_id | string | No | A person's decision on the held action, present once it is approved or rejected. It changes only when a new decision is made, so a reader acts once per decision_id. |
entity | Entity | Yes | |
explain | object | No | The ledger: each node's value, unit and source behind the result. |
model_release_id | string | No | The model release that produced a lane's result. |
note | string | No | What the item's action comes to, as a sentence for a person: the swap to make, or why there is none to act on (no backup pass, waiting for approval, rejected, shown for review). |
quantity | string | No | What a lane result's value measures, such as snr_db or rx_power_dbm. |
series | array of Point | No | Values over the result's span, in time order. |
severity | string | No | known values: info, warning, critical. Absent means info. Known values: info, warning, critical; read any other as info. |
target_at | date-time | Yes | When the result applies (UTC, ISO 8601). |
unit | string | No | The unit of a lane result's value, such as dB or dBm. |
until | date-time | No | The end of the result's span, for a result over a span. |
value | Value | Yes | |
workflow_version | integer | No | The workflow version that produced a workflow's result. |
3. Act on each approval exactly once
An item's action is an instruction only when action_status is approved and action is present. Advice (an action with no action_status), pending, rejected and any status you do not know are never acted on.
| Field | Type | Required | The contract allows |
|---|---|---|---|
deadline | date-time | No | |
from | string | No | |
gain_gb_p10 | number | No | |
mode | string | Yes | known values: suggest, approve. Known values: suggest, approve. |
to | string | No | |
to_antenna_id | string | No | |
to_at | date-time | No | |
verb | string | Yes | known values: reroute, swap. Known values: reroute, swap. A reader skips a verb it does not know. |
- Exactly once. An approval stands: every later run sends it again, and approving republishes the run. Keep the keys you acted on, keyed by
decision_id(orentity.id|verb|towithout one), and act only on a key you have not seen. A new approval of the same action has a newdecision_id: act on that one too. - Before the cancel deadline. Never act on an action whose
deadlinehas passed: the provider's cancellation window is closed. - Survive restarts. Save the acted keys before you save the cursor, so a restart between the two never acts twice. Forget a key 7 days after the latest of the item's
target_at,untiland the action'sdeadline.
4. Report each run
After applying a run, POST /predictions/feed/deliveries once with what you wrote. It answers 204. applied holds counts named as you like, shown in the Platform as "wrote 12 passes"; acted counts the approved actions you carried out.
| Field | Type | Required | The contract allows |
|---|---|---|---|
applied | object of integer | No | at most 20 entries |
consumer | string | Yes | matches `^[a-z0-9][a-z0-9-]{0,62}$` |
cursor | string | Yes | 1 to 128 characters |
run_id | string | Yes | matches `^run_\d{8}T\d{6}_[0-9a-f]{8}$` |
target | string | No | at most 200 characters |
Test it
The constellation CLI's mock API serves a demo feed with every action state, and its conformance check runs any bridge command (in any language) against it, kills and restarts it, and checks every rule on this page:
constellation mock # the demo feed on http://localhost:7070
constellation conformance -- ./my-bridge # 21 checks; prints conformant when all pass
Your bridge reads CONSTELLATION_API_URL and CONSTELLATION_API_KEY, and for the check also CURSOR_FILE, POLL_SECONDS and CONSTELLATION_CONFORMANCE_LOG, where it appends one JSON line per item it applies. Build a connector lists the checks and the log line, and CLI how to install it. The SDKs' Bridge classes do all of this for you, if you would rather not write it.