Grid API quickstart

This walkthrough exercises one complete API loop: readiness → deploy → subscribe → write → resolve → delete.

Before you begin

You need a running Grid Server Build, curl, and jq. Obtain the public API bearer token from your operator; it is not the Runtime Host, admin, or connector-ingress token.

export GRID_URL="http://localhost:3000"
export GRID_TOKEN="replace-with-your-api-token"

1. Check readiness

curl --fail-with-body "$GRID_URL/readyz" | jq

Readiness probes deliberately do not require the public API token. A 200 response with status: "ok" means the deployment is ready to receive traffic. Do not use liveness alone for this decision.

2. Deploy a model

curl --fail-with-body \
  -H "Authorization: Bearer $GRID_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$GRID_URL/api/models" \
  --data-binary '{
    "id": "revenue-api",
    "protectedMode": true,
    "source": "MODEL \"Revenue API\"\n\ninput Revenue = 100000\ninput TaxRate = 0.21\noutput NetRevenue = Revenue * (1 - TaxRate)\n\nEND MODEL"
  }' |
  jq '{id, sourceHash, declaredInputs, declaredOutputs, diagnostics}'

Keep the returned sourceHash if you plan to replace the source later. Protected mode limits writes to declared inputs.

3. Open its event stream

In another terminal, connect before changing the input:

curl --no-buffer \
  -H "Authorization: Bearer $GRID_TOKEN" \
  "$GRID_URL/api/models/revenue-api/events"

The stream begins with control-plane synchronization. It is not a dump of every evaluated value; clients fetch the values or ranges they need after adopting the current model snapshot.

4. Change an input

curl --fail-with-body \
  -H "Authorization: Bearer $GRID_TOKEN" \
  -H "Content-Type: application/json" \
  -X PUT "$GRID_URL/api/models/revenue-api/input" \
  --data '{"symbol":"Revenue","value":120000}' |
  jq '{symbol, status, value, requestRev, resolvedRev, lastError}'

The open stream should emit a symbol:update after the new revision settles.

5. Read the result

curl --fail-with-body \
  -H "Authorization: Bearer $GRID_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$GRID_URL/api/models/revenue-api/symbols/resolve" \
  --data '{"symbols":["NetRevenue"]}' |
  jq '.NetRevenue.value.value'

Expected numeric leaf:

94800

The surrounding symbol snapshot also carries status and server-owned request/resolution revisions.

6. Delete the model

curl --fail-with-body \
  -H "Authorization: Bearer $GRID_TOKEN" \
  -X DELETE "$GRID_URL/api/models/revenue-api"

The response is the JSON boolean true when a model was deleted.

Next steps

• Use model lifecycle for compare-and-swap source and input writes.
• Use realtime events to implement heartbeat detection and reconnect synchronization.
• Read API conventions before adding retry behavior.