Backend capability reference
Pulse Runtime API
The Pulse runtime API is the public developer surface for trusted backend behavior in Vibecodr projects.
Public Pulse runtime API reference for trusted Vibecodr backend code.
Implementation focus
Use this reference when writing or reviewing Pulse handlers that call providers, use secrets, coordinate duplicate work, or expose app-facing responses.
Expected outcomes
- Choose the right handler shape.
- Use runtime capabilities through documented `env` helpers.
- Return safe app-facing failures.
- Keep provider credentials and diagnostics out of public responses.
Handler shapes
Pulse handlers are trusted backend code for work that should not run in the browser. Use `definePulse()` when you want the enhanced Vibecodr runtime helpers, and use `defineWebPulse()` when a web-standard Request and Response shape is the clearest contract.
Both styles should validate method, payload, authorization, and response shape explicitly. Public callable routes are not automatically safe just because the source is private.
- `definePulse()` is the ergonomic path for runtime capabilities such as secrets, connections, state, logging, and app metadata.
- `defineWebPulse()` is useful when you want a handler that reads like a Fetch API endpoint.
- Keep route behavior stable once vibes, embeds, webhooks, or agents depend on it.
Runtime capabilities
The Pulse runtime exposes curated capabilities through `env`. The important public contract is what the handler can rely on, not the private host that delivers it.
Use `env.fetch` for outbound calls that should follow Vibecodr capability policy, `env.secrets` for server-side credentials, `env.connections` for connected-account calls, `env.state` for duplicate-safe operation memory, `env.request` for request context, `env.log` for owner-visible diagnostics, and `env.runtime.capabilities()` for safe capability reflection.
- Do not probe raw host environment objects.
- Keep secret values out of responses and logs.
- Use `env.db` only when the plan and project shape make SQL compatibility the right data surface.
- Prefer small explicit JSON responses that the vibe can handle predictably.
Failure behavior
A Pulse can reject a request because the method is wrong, the body is too large, JSON is invalid, auth is missing, a secret or connection is not configured, a provider is unavailable, or the operation would exceed plan limits.
Handlers should translate those failures into stable app-facing responses. The viewer needs enough information to recover or retry safely, not provider tokens, stack traces, private source, or platform diagnostics.
- Return 405 for unsupported methods when the route is method-specific.
- Return 400 for malformed input that the caller can fix.
- Return 401 or 403 for missing or rejected access checks.
- Return 413 when the request belongs in an upload/storage flow instead of a Pulse call.
Example and read next
Example: a Pulse route needs to call a provider and remember duplicate work. Use definePulse, env.fetch, env.secrets or env.connections, env.state, env.log, and env.runtime.capabilities() from the documented runtime surface.
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 SDK & Handlers
- Read next: Pulse State
- Read next: Secrets & APIs
- Read next: Calling Pulses