Ctrl K

Guides API Reference Examples Pricing Help Center

APIGeneration Events

Generation Events

During a generation run, Logic64 streams live progress to the client over a persistent HTTPS connection using Server-Sent Events. Seven typed event names cover everything from individual output tokens to the final bundle confirmation. Studio consumes this stream automatically. This page documents the event protocol for developers building custom integrations.

Why Server-Sent Events

Logic64 uses SSE as the sole streaming transport. SSE is a one-way channel — the server pushes events; the client listens. There are no bidirectional channels, no WebSockets, no long-polling. The design is deliberate:

Plain HTTP. SSE runs over a standard HTTPS connection. It passes through every corporate proxy, CDN, and load balancer without special configuration.
Simple client model. The client opens one connection and reads a stream of named events. No handshake protocol, no message framing, no bidirectional state to manage.
Generation is inherently one-way. The Engine produces output; it does not need to receive input mid-run. A unidirectional channel is the correct abstraction for this flow.
ACK is always a separate POST. Bundle acknowledgement is an intentional action, not an inline message on the stream. Keeping them separate prevents accidental confirmation and makes audit logging straightforward.

How to consume the stream

Studio handles this automatically. If you are using Logic64 Studio, the stream is consumed on your behalf — no integration work required. The information below is for developers building custom clients or CLI integrations.

A custom client opens a long-lived HTTPS connection to the generation stream endpoint, authenticated with the same Bearer token used for all other API calls. The connection stays open until a terminal event (bundle_ready or error) is received, or until the client disconnects.

Authenticate every request with your API key in the Authorization: Bearer <key> header.
Read events as they arrive. Each event has a named type and a JSON payload. Process or ignore event types as your integration requires.
bundle_ready and error are terminal — the stream closes after either one. Do not wait for more events.
After bundle_ready, call GET /bundles/:id/download to retrieve the bundle, then confirm with POST /bundles/:id/ack.

Event format

Every event follows the standard SSE wire format: an event field naming the event type, followed by a data field containing a JSON object, terminated by a blank line.

sseillustrative

event: token
data: {"delta": "export default function App() {"}
event: tool_status
data: {"action": "Generating src/app/page.tsx"}
event: bundle_ready
data: {"bundle_id": "a3f2bc89-4d1e-47a0-b8c6-2e5f91340abc"}

The payloads above are illustrative. Field names shown are for orientation only — the canonical schema is versioned server-side. Each event type is described semantically in the sections below.

Event types

Seven event types are emitted during a generation run. Two are terminal — they signal the end of the stream.

token — partial output chunk produced during file generation.
state_update — an architectural decision or stack constraint has been locked.
memory_update — the project memory document has been revised.
tool_status — the Engine is performing a named action (e.g., generating a file, validating, finalizing).
bundle_ready — terminal success. The bundle has been finalized and is ready for download.
cost_summary — token usage and cost accounting for the completed run.
error — terminal failure. The run could not be completed.

token

Emitted continuously during file production. Each token event carries a small slice of the generated output — typically a fragment of source code or configuration text. Concatenating all token deltas for a given file reconstructs its full content. Studio renders these tokens in real time as the Engine writes each file.

state_update

Emitted when the Engine locks an architectural decision — for example, committing to a specific framework, runtime version, or project constraint. State updates reflect changes to the architectural record that governs the remainder of the generation. Studio uses these events to keep the architecture panel in sync during the run.

memory_update

Emitted when the Engine revises the project memory document. Memory holds durable context about the project — decisions, constraints, and notes that persist across runs. A memory_update event signals that this document has changed and carries the updated content so the client can reflect the new state immediately.

tool_status

Emitted each time the Engine starts a significant action: generating a specific file, running cross-file validation, finalizing the bundle, and so on. These events give the client a live progress signal without requiring it to parse token content. Studio displays the current action as a status line while generation is in progress.

bundle_ready

terminal

Terminal success event. Emitted once — when the full bundle has passed all validation checks and has been packaged. The payload conveys the bundle ID needed to download and acknowledge the bundle. After this event the stream closes; no further events are emitted. See After bundle_ready for the next steps.

cost_summary

Emitted at the end of a successful run, immediately before or after bundle_ready. It carries token usage counts and the estimated cost for the completed generation. Clients can use this data to display a run summary or to feed usage dashboards.

error

terminal

Terminal failure event. Emitted when the Engine encounters an unrecoverable condition — a validation failure that exceeds the retry limit, an upstream service outage, or a constraint violation that cannot be resolved. After an error event the stream closes. No bundle is produced. The payload describes the failure so the client can surface a meaningful message to the developer.

Reconnection

Network interruptions can drop a long-lived SSE connection before generation completes. Clients should implement automatic reconnection with exponential backoff — wait a short interval, double it on each retry, and cap at a reasonable maximum (e.g., 30 seconds).

Studio handles reconnection automatically. If your custom client reconnects, it should resume reading from where the stream left off — events already delivered before the drop do not need to be re-processed.

Reconnection support is built into the SSE standard. The Last-Event-ID header can be used to communicate the last received event to the server on reconnect, enabling the stream to resume from the correct position.

After bundle_ready

When bundle_ready arrives, the generation run is complete. The payload carries the bundle ID. From here, the flow is two explicit HTTP calls:

Download: GET /bundles/:id/download — retrieves the validated bundle ZIP. The ZIP contains all generated files and a manifest.json that describes routing instructions for each file.
Acknowledge: POST /bundles/:id/ack — confirms that the bundle was received. ACK is the primary deletion trigger; bundles not acknowledged expire after 24 hours.

The CLI (logic64 pull <bundle-id>) performs both steps automatically after you supply the bundle ID shown in Studio. For API integrations, see the API Reference for full endpoint details and response schemas.

Next steps

Now that you understand the event protocol, explore the full REST surface and usage limits.