Runtime invocation patterns

Calling Pulses

This guide focuses on request flow between vibes and Pulses, including same-origin /api calls, public endpoint access, platform-mediated grants, auth context, payload shape, and error handling expectations.

Invocation guidance for predictable vibe-to-Pulse communication.

Implementation focus

Apply this when wiring fetch calls from client code to Pulse routes or when stabilizing production request contracts.

Expected outcomes

Call Pulse endpoints with consistent auth and error behavior.
Design payloads that survive future handler evolution.
Reduce production regressions from ad-hoc request semantics.

Client call contract

Vibes call Pulses through same-origin /api routes. The client should send the smallest useful payload and expect structured responses with clear success and failure states.

Avoid coupling the client to provider-specific errors or internal platform details. The Pulse should translate backend concerns into a stable app-facing contract.

Use relative /api paths from the vibe when possible.
Send JSON payloads with explicit fields.
Handle non-2xx responses in the client.
Keep auth and validation rules in the Pulse handler for protected behavior.

Client call from a vibe typescript

const response = await fetch("/api/send-message", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ message })
});

const payload = await response.json();
if (!response.ok) {
  throw new Error(payload.error ?? "Pulse call failed");
}

Request and upload limits

Pulse calls are for compact request data, webhooks, and app commands. They are not the large-file upload path for media, archives, or user-generated assets.

The API run endpoint JSON envelope is capped at 64 KiB. Direct public runtime calls through the Pulse runtime host accept non-GET/HEAD request bodies up to 1 MiB before returning 413 pulse.requestBodyTooLarge.

Use storage, import, or image-upload surfaces for larger files.
Pass a small id, URL, or metadata object to the Pulse after upload.
Treat 413 responses as a request-shape issue, not a transient runtime failure.

Failure and auth behavior

A vibe should treat Pulse calls as networked backend calls, not as local helper functions. The request can fail, the payload can be invalid, the endpoint can reject the viewer, and the external provider behind the Pulse can be unavailable.

Protected behavior should fail closed in the Pulse and return an app-facing error that does not reveal secrets, internal grants, provider tokens, deployment details, or raw stack traces.

Use session, signature, or owner-defined checks for restricted endpoint behavior.
Return stable error codes or messages that the vibe can render safely.
Avoid retry loops in the browser unless the operation is idempotent.
Keep provider-specific diagnostics in owner-visible logs, not viewer-visible responses.

Example and read next

Example: a vibe submits form data to /api/send-message. Send explicit JSON, handle non-2xx responses, and let the Pulse translate provider failures into a stable app-facing error.

Use these related pages when you need the next layer of guidance. They point to the most likely follow-up tasks, not every page that happens to touch the same system.

Read next: Pulse Routing (/docs/pulse-routing)
Read next: Pulse SDK & Handlers (/docs/handlers)
Read next: Secrets & APIs (/docs/secrets)
Read next: How-To Guides (/docs/how-to)