Send connector events to Grid

Connector ingress delivers data only to bindings already declared or configured for the exact source ID. It is not an arbitrary model-cell write endpoint.

Authenticate

Use the connector-ingress bearer credential issued by your operator:

Authorization: Bearer <ingress-token>

Do not assume it is interchangeable with the public API token. Per-source and global token precedence is deployment-sensitive and should be verified end to end by the operator.

Send sparse events

curl --fail-with-body \
  -H "Authorization: Bearer $GRID_INGRESS_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$GRID_URL/api/pipes/sources/weather/events" \
  --data '{
    "sourceKind": "stream",
    "events": [
      {
        "sourceSymbol": "temperature",
        "value": 21.5,
        "typeTag": "number",
        "sequence": 7,
        "idempotencyKey": "weather-temperature-7",
        "metadata": { "key": "station-ord" }
      }
    ]
  }'

Allowed sourceKind values are grid-model, webhook, polling, stream, and adapter. sourceSymbol and value are required. typeTag, sequence, idempotencyKey, and metadata are optional; stable idempotency keys are strongly recommended. Omit observedAt until your deployment's event-time contract has been verified.

Interpret the response

... | jq '{sourceId, admitted, deduped, coalesced, unbound, applied, stream}'

• admitted: newly accepted deliveries.
• deduped: already accepted deliveries.
• unbound: events without a matching delivery binding.
• applied: writes applied to locally resident target models.
• stream.batchStatus: empty, unsubscribed, appended, or duplicate.

The response can include deeper runtime health metadata. That deeper shape is not documented here as a stable integration contract.

Send a dense range frame

This request carries the row-major bytes [10, 20, 30, 40] as a 2×2 unsigned-byte frame:

curl --fail-with-body \
  -H "Authorization: Bearer $GRID_INGRESS_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$GRID_URL/api/pipes/sources/sensor-grid/range-frame" \
  --data '{
    "targetModelId": "sensor-demo",
    "x": 0,
    "y": 0,
    "width": 2,
    "height": 2,
    "sequence": 42,
    "encoding": "u8-base64",
    "presentation": "heatmap",
    "values": "ChQeKA==",
    "min": 0,
    "max": 255,
    "source": "sensor-grid"
  }'

Supported ingress encodings are u8-base64 and little-endian f64-base64. A successful dense response includes ok, modelId, sourceId, rangeSource, sequence, cells, opsRecomputed, and analysisCells. The public maximum frame size is not documented because current layers disagree; test against the exact deployed build.

Retry safely

Honor Retry-After on overload. Reusing an idempotency key with conflicting content can return 409. Preserve the source ID, sequence, idempotency key, response status, and retry header when troubleshooting.