Quickstart with curl

This is the smallest possible Engine quickstart. If you have curl, you have everything you need.

Set your environment

Replace the values with your own:

export ENGINE_URL=http://localhost:8000
export ENGINE_KEY=dev-engine-key

Confirm the Engine is reachable

curl -fsS "$ENGINE_URL/health"

You should get back something like:

{
  "status": "ok",
  "uptime_seconds": 12.5,
  "subsystems": { "...": "..." }
}

/health is the only endpoint that doesn’t require an API key. If this doesn’t return, your Engine isn’t running yet — check Local development quickstart.

Send your first message

curl -N -X POST "$ENGINE_URL/execute" \
  -H "Content-Type: application/json" \
  -H "X-Engine-Key: $ENGINE_KEY" \
  -d '{
    "message": "Say hello in one short sentence.",
    "task_id": "demo-001"
  }'

The -N flag disables curl’s output buffering so you see Server-Sent Events as the Engine emits them. You should see something like:

event: thread_lifecycle
data: {"phase":"started","task_id":"demo-001"}

event: text_delta
data: {"text":"Hello — "}

event: text_delta
data: {"text":"good to "}

event: text_delta
data: {"text":"meet you."}

event: thread_lifecycle
data: {"phase":"completed","task_id":"demo-001"}

The text_delta events are the model’s response, streamed token by token. You can concatenate them yourself or use a client library that does it for you.

Continue the conversation

Use the same task_id to continue the thread. The Engine remembers everything that came before:

curl -N -X POST "$ENGINE_URL/execute" \
  -H "Content-Type: application/json" \
  -H "X-Engine-Key: $ENGINE_KEY" \
  -d '{
    "message": "Repeat what you just said in French.",
    "task_id": "demo-001"
  }'

Reconnect to a stream you missed

If your client disconnected mid-stream, replay any events you missed since a given timestamp:

curl -N "$ENGINE_URL/execute/replay?after=0" \
  -H "X-Engine-Key: $ENGINE_KEY"

after is a millisecond timestamp. 0 replays everything available.

Where to go next

Streaming events reference — every event type the Engine can emit.
Quickstart in Python or Node — same flow with a real client library.
The agent loop — what’s happening on the server while you watch the stream.

​Set your environment

​Confirm the Engine is reachable

​Send your first message

​Continue the conversation

​Reconnect to a stream you missed

​Where to go next