Block Templates — Combinations That Work
Copyable block combinations for everyday use cases: API endpoints, forms, validation, file uploads, and email. Wire them once, reuse the shape forever.
Most flows are variations on a handful of proven shapes. These templates give you the exact blocks, in order, with their connections — grab them onto your canvas and adjust the details. Every block type below exists in the current block library; search its name in the editor to add it. For broader recipes with notes and pitfalls, see Common Blueprint Patterns.
1. API Endpoint
The universal shape of every custom API: trigger, work, reply.
| Block | Purpose | Connects to |
|---|---|---|
on_startup_register_uri_get | Registers GET /api/v1/<uri> and fires per request. | function → trigger's function handler |
trigger_custom_function | The handler function entry point. | flow → your work blocks |
httpconnection_current_request | The live request connection object. | connection → every request/response block that needs it |
Work blocks (e.g. function_search, object_new_fields) | Read/write data, build the payload. | flow chain; data pins as needed |
httpconnection_set_json | Replies with JSON to the caller. | flow (end of chain), connection, code ← number_default (200/400/401), data ← your payload |
Variants: swap the trigger for on_startup_register_uri_post (body in, e.g. webhooks), add a branch for validation splits, or a second httpconnection_set_json on the error path. Full walkthrough: Build Your First API.
2. Form Handling
Collect input on a page and write it to storage on submit.
| Block | Purpose | Connects to |
|---|---|---|
state_form | The form container element. | renders on the page; receives child elements on content |
state_input_dynamic | A typed input field (text, number, date, etc.). | state → form content |
state_button | The submit button with a click event. | state → form content; click triggers the submit flow |
state_form_get | Reads the submitted form (form-object with all field values, form-error on failure). | first block of the submit flow |
mutations_set_bp_field_multiple | Maps form values to document fields. | mutations → create/update block |
function_create_document_from_mutations | Writes the document. | flow ← submit flow, storage ← storage block |
Step-by-step with screenshots: Build Your First CRUD App.
3. Data Validation
Reject bad input before it reaches storage or an external API.
| Block | Purpose | Connects to |
|---|---|---|
condition_not_empty_value | true when the checked field is filled. | one per required field, fed from form-object or request params |
branch | Splits the flow on a condition into true/false paths. | condition ← the validation blocks |
httpconnection_set_json (API) or a UI message (pages) | The rejection: 400 with an error object, or inline form feedback. | false path; true path continues to the save/work flow |
Keep one condition block per field — the user learns exactly which field failed, instead of "something was wrong".
4. File Uploads
Accept files through an API and store them as cluster assets.
| Block | Purpose | Connects to |
|---|---|---|
on_startup_register_uri_post | Receives the upload request (multipart body). | function handler |
Files-group blocks (search file in the block library) | Read the uploaded file, its name/type/size. | fed by the request body |
file_from_assets | Reads a file from cluster assets (/public/... or /system_assets/...). | asset path ← value; out file, size, success |
Asset upload API (POST /api/v1/_system/assets/stream) | Stores the file into public or system_assets. | alternative to a custom flow — often enough on its own |
Everything about asset paths, public vs private, and the upload APIs: Assets.
5. Email Sending
Send transactional email through Postmark, driven by a flow.
| Block | Purpose | Connects to |
|---|---|---|
Any trigger (form submit, storage_event, schedule_repeating_event) | Decides when an email goes out. | start of the flow |
| Data blocks (search/get) | Collect recipient and content (user profile, order, template values). | value pins into the email fields |
Postmark send blocks (search postmark in the block library) | Send the message via the cluster's Postmark token. | to/subject/body from your data; token from postmark_token system setting |
function_console_log | Record success/failure while developing. | message ← send result or error pin |
Prerequisite: postmark_token (secure) and email_default_from must be set — see Email configuration. For heavy or batched mail, defer to the queue instead of sending inline.
6. Template or From Scratch?
- Use a template shape when the job is a known pattern: endpoint, form write, validation, upload, notify. It saves wiring and keeps conventions uniform across your cluster.
- Go from scratch when the data model or the flow is genuinely yours: unusual branching, multi-storage orchestration, custom UI state. Start from the closest template and prune rather than starting empty.
- Extract to a function once you paste the same three blocks twice — see Blueprint Best Practices.