Skip to main content

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.

FieldTypeRequiredThe contract allows
bridge_versionstringNoat most 40 characters
canGrantsNo
consumerstringYesmatches `^[a-z0-9][a-z0-9-]{0,62}$`
manifestConnectorManifestNo
mapping_versionsarray of integerNoat most 10 items
system"yamcs" or "lattice" or "cosmos" or "custom"Yes
system_versionstringNoat most 40 characters
targetstringNoat most 200 characters
widgetInstalledNo

The manifest:

FieldTypeRequiredThe contract allows
descriptionstringNoat most 300 characters
namestringYesmatches `^[a-z0-9][a-z0-9-]{0,62}$`
settingsobjectNoat most 20 entries
titlestringYes1 to 80 characters

Each of its settings:

FieldTypeRequiredThe contract allows
defaultboolean or integer or number or stringYes
descriptionstringNoat most 300 characters
max_lengthintegerNo1 to 2000
maximumnumberNo
minimumnumberNo
optionsarray of stringNoat most 20 items
titlestringYes1 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.

FieldTypeRequiredThe contract allows
afterstringNo
limitintegerNo1 to 20; default 20
consumerstringNomatches `^[a-z0-9][a-z0-9-]{0,62}$`
page_recordsintegerNo1 to 5000
cursorstringNo1 to 128 characters
pageintegerNoat least 0; default 0
from"latest"No
  • First start. With no saved cursor, call it with from=latest. It answers no entries and a next just 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 cursor once you have applied and reported it, somewhere that survives a restart (a volume, or your system), and send it as after. 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. oldest is 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 with cursor and page until there is no next_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:

FieldTypeRequiredThe contract allows
actionActionNo
action_idstringNoA held action, the same on every run that suggests the same verb on the same entity to the same target.
action_statusstringNoknown 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_idstringNoA 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.
entityEntityYes
explainobjectNoThe ledger: each node's value, unit and source behind the result.
model_release_idstringNoThe model release that produced a lane's result.
notestringNoWhat 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).
quantitystringNoWhat a lane result's value measures, such as snr_db or rx_power_dbm.
seriesarray of PointNoValues over the result's span, in time order.
severitystringNoknown values: info, warning, critical. Absent means info. Known values: info, warning, critical; read any other as info.
target_atdate-timeYesWhen the result applies (UTC, ISO 8601).
unitstringNoThe unit of a lane result's value, such as dB or dBm.
untildate-timeNoThe end of the result's span, for a result over a span.
valueValueYes
workflow_versionintegerNoThe 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.

FieldTypeRequiredThe contract allows
deadlinedate-timeNo
fromstringNo
gain_gb_p10numberNo
modestringYesknown values: suggest, approve. Known values: suggest, approve.
tostringNo
to_antenna_idstringNo
to_atdate-timeNo
verbstringYesknown 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 (or entity.id|verb|to without one), and act only on a key you have not seen. A new approval of the same action has a new decision_id: act on that one too.
  • Before the cancel deadline. Never act on an action whose deadline has 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, until and the action's deadline.

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.

FieldTypeRequiredThe contract allows
appliedobject of integerNoat most 20 entries
consumerstringYesmatches `^[a-z0-9][a-z0-9-]{0,62}$`
cursorstringYes1 to 128 characters
run_idstringYesmatches `^run_\d{8}T\d{6}_[0-9a-f]{8}$`
targetstringNoat 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.