Watching changes

For the integration that must notice a change rather than poll for it: the SSE stream that reports the file set on every change, the ticket that opens it from a client that cannot set a header, and — part of an Enterprise agreement — the downstream-impact read that says what a changed file moves.

GET/v1/projects/{projectId}/files/streamSession

Subscribe to file changes

Hold an SSE connection open and receive the file list on every change — how you watch an ingestion settle.

A baseline frame arrives immediately on connect — `[]` when the project is empty — so you can tell "connected, nothing here" from "no frame yet".

A file leaving the set arrives as an `{id, removed}` tombstone. The connection heartbeats every 25 seconds; a missed heartbeat means reconnect.

The same `/stream` suffix exists on `cells`, `entities`, and `factions`.

Path parameters

Field	Type	Required	Description
projectId	string	required	The project to watch.

Request · curl

curl -X GET "https://runlog-7613480744.us-central1.run.app/v1/projects/p7Kd2mQx/files/stream" \
  -H "Authorization: Bearer $RUNLOG_SESSION_TOKEN" \
  -H "X-Project-Id: p7Kd2mQx"

Response · 200

data: [{"fileId":"4mHqZ1nR8vTbC0sWyLpAeGkJ3dXfU6iO2rN","status":"ready"}]

Errors

Status	error	When
404	project not found	The project does not exist, or you have no access to it. Projects are non-enumerable, so a denied read is indistinguishable from a missing one.
401	invalid API key	The `Authorization` header is missing, malformed, or names a revoked key.
400	name the target project via the X-Project-Id header or projectId query	No project was named and the key is not bound to one.
429	rate limit exceeded	You passed 60 requests/minute on this key. `Retry-After` carries the seconds to wait.
500	internal error	The relay failed to serve the request. Retry with backoff; the cause is logged server-side against your request.

POST/v1/api/projects/{projectId}/files/stream-ticketAPI key

Mint a file-stream ticket

Receive the short-lived ticket that opens the project's file stream without a header.

The agent-run stream's precedent, on the file stream: a normal keyed call mints a ticket that opens the stream once, within 120 seconds, so the key itself never travels in a URL. Mint one per connection.

Path parameters

Field	Type	Required	Description
projectId	string	required	The project whose file stream to open.

The flow

# 1. Mint a ticket: a normal keyed call.
curl -X POST "https://runlog-7613480744.us-central1.run.app/v1/api/projects/p7Kd2mQx/files/stream-ticket" \
  -H "Authorization: Bearer $RUNLOG_API_KEY"
# → {"ticket": "st_7Qk2Mv…", "expiresInSeconds": 120}

# 2. Open the stream with it. No header, so EventSource can.
curl -N "https://runlog-7613480744.us-central1.run.app/v1/projects/p7Kd2mQx/files/stream?ticket=$TICKET"

Request · curl

curl -X POST "https://runlog-7613480744.us-central1.run.app/v1/api/projects/p7Kd2mQx/files/stream-ticket" \
  -H "Authorization: Bearer $RUNLOG_API_KEY" \
  -H "X-Project-Id: p7Kd2mQx"

Response · 200

{
  "expiresInSeconds": 120,
  "ticket": "st_7Qk2Mv…"
}

Errors

Status	error	When
404	project not found	The project does not exist, or you have no access to it. Projects are non-enumerable, so a denied read is indistinguishable from a missing one.
401	invalid API key	The `Authorization` header is missing, malformed, or names a revoked key.
400	name the target project via the X-Project-Id header or projectId query	No project was named and the key is not bound to one.
429	rate limit exceeded	You passed 60 requests/minute on this key. `Retry-After` carries the seconds to wait.
500	internal error	The relay failed to serve the request. Retry with backoff; the cause is logged server-side against your request.