TypeScript API client

import { createCerealClient } from "@trycereal/sdk/client"
import { CerealError, SessionNotFoundError } from "@trycereal/sdk"

const client = createCerealClient({ apiKey: process.env.CEREAL_API_KEY })

Calls go to https://app.trycereal.ai. apiKey defaults to CEREAL_API_KEY in a Node process. The constructor requires a credential, unless headers.authorization supplies one explicitly. It does not read the CLI's saved login. Constructing a client makes no request.

Configuration

An API key is bound to exactly one environment and selects it automatically. A supplied x-cereal-environment header must match that environment; a mismatch fails. Personal credentials can select an environment and organization with tenancy headers. See credentials for the scoping rules. Use headers for additional request headers and fetch to supply an application transport.

Configuration signature · Constructor

Direct clients operate on explicit resources; they do not register local provider or agent definitions. Use declarative authoring for automatic initialization. getCerealClient() from the root uses the same application runtime as your initialized agents.

Surface

Use the generated TypeScript namespace reference for the method you actually call:

HTTP operation names are not a complete list of SDK methods. Consult HTTP coverage before assuming a wrapper exists, and use HTTP reference for an operation without a wrapper.

Streaming, server-side

for await (const event of client.sessions.stream(sessionId, {
  after: lastSeq,
  signal: controller.signal
})) {
  console.log(event.type)
}

This helper first mints a stream token, then consumes the SSE route in cereal format. It requires data scope for token minting, and returns projected events rather than raw event-log rows. It requests all disclosure groups by default; use include to narrow those groups. The helper is a single stream connection; it does not provide the browser subscriber's automatic reconnect loop. Retain a cursor and reopen if your job needs to resume.

For a browser, mint a token on your server and use browser helpers. For a finite durable-history read, call client.sessions.events, which requires read.

Results and errors

Results are plain JSON with ISO timestamp strings. The SDK handles the wire encoding of write-only secrets for operations such as provider registration.

try {
  const session = await client.sessions.get({ id: sessionId })
  console.log(session.status)
} catch (error) {
  if (error instanceof SessionNotFoundError) console.log("Session not found")
  else if (error instanceof CerealError) console.error(error.tag, error.data)
  else throw error
}

Known server failures become CerealError subclasses. Unknown server tags remain CerealError values carrying tag and data. Transport failures use CerealTransportError; validation failures use CerealValidationError. Import these classes from @trycereal/sdk. Use stable idempotency keys when retrying creates or sends; retrying every error is not a safe default. HTTP errors explains server failure tags.