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.