observable-query-curl

Debug Observable Queries with cURL

Use this skill to help the user work with observable query endpoints from a terminal.

The main choice is:

1. Snapshot GET — return the current observable value once
2. Wait for first payload — block until the first payload exists
3. SSE stream — keep the connection open and follow updates
4. Long polling — repeat blocking HTTP requests instead of keeping one stream open

Step 1 — Identify the endpoint style

Figure out whether the user has:

• a model-bound observable query route
• a controller-based observable query route
• the observable query demultiplexer SSE endpoint

If the user does not know the route yet, help them find it before suggesting commands.

Step 2 — Choose the correct cURL workflow

A. Get the current snapshot

Use a plain GET when the user wants the current observable value right now.

curl "https://localhost:5001/api/orders/observe-all"

Explain that this returns the current QueryResult snapshot once and then closes.

B. Wait for the first payload

Use waitForFirstResult=true when the observable might not have produced its first value yet.

curl "https://localhost:5001/api/orders/observe-all?waitForFirstResult=true"

If the user wants a custom timeout, add waitForFirstResultTimeout=<seconds>.

curl "https://localhost:5001/api/orders/observe-all?waitForFirstResult=true&waitForFirstResultTimeout=10"

Explain that:

• the timeout value is in seconds
• the response is still a normal JSON QueryResult
• if the observable is not ready and waiting is not enabled, the endpoint can return a not-ready response instead of blocking

C. Stream JSON continuously with SSE

Use SSE when the user wants the observable to keep pushing updates over one connection.

curl --no-buffer \
  -H "Accept: text/event-stream" \
  "https://localhost:5001/api/orders/observe-all"

Explain that:

• Arc sends SSE frames such as data: {...}
• each frame contains a serialized QueryResult
• --no-buffer helps cURL print each event as it arrives