Actions and templates
The eleven actions, the ref, which relay can fulfil or refund, and templates.
Actions
A relay runs one to ten of these, in order.
| Action | Fields | What it does |
|---|---|---|
write_record | collection, data, to?: "person" | Writes a record, keyed per event, so a retry never duplicates it. The write goes through the same checks as a write from your app, so the plain-text and file rules apply. to: "person" addresses the record to the event's person and is required on addressed and direct collections. The record is app-owned, like a receipt |
grant_access | entitlement (a plan or product name, or access:<slug>), expiresAt? ("30d", "12h", "2w" or an ISO date), reason? (up to 200 characters, templated) | Grants access with the seventh grant source, relay. The person's page reads "granted by relay <name>". No key can create a grant with this source |
revoke_access | entitlement | Ends every live grant of that entitlement the person holds |
grant_credits | amount (1 to 10,000), reason? (up to 200 characters, templated), expiresInDays? (1 to 3,650) | Adds a promotional grant to the person's credit balance, once per event. It is the first to burn. With expiresInDays, what is left ends that many days after it lands. The ledger line reads "relay: <reason>" |
fulfil_product | product (a product name), ref? (up to 200 characters, templated) | Grants the product's key and credits to the event's person and writes the receipt, the same as a Stripe purchase. See The ref and Which relay can fulfil or refund |
refund_product | product (a product name), ref? (up to 200 characters, templated) | Takes back what fulfil_product granted under the same ref. Can run from any relay |
grant_plan | plan (a plan name), ref? (up to 200 characters, templated) | Makes the event's person's subscription on that plan active, linked to the relay event and with no Stripe customer id. It grants the plan's key with the subscription as its source and records the payment under ref: the same steps a Stripe invoice takes. A renewal is a new ref that keeps the plan active. One active plan per person. Active until revoke_plan. Only for a plan sold through this relay |
revoke_plan | plan (a plan name), ref? (up to 200 characters, templated) | Ends the person's relay-granted subscription on that plan. They move to the default plan, and the key grant_plan gave is revoked; grants made by hand or by a purchase stay. Can run from any relay |
email_person | subject (up to 300), text (up to 10,000), kind? event or account | Emails the event's person. It shares notify()'s caps (200 per app per hour and five event sends per person per day) and your sends switch. Like notify(), it sends only from your verified sender domain, from that domain's news address (kind account uses its account address). Until a domain is verified on the Domains page, this action alone is refused with sender_domain_required, and the event's result says so. Nothing is sent via Gemmein |
call_url | url | POSTs the event to your URL (see Calling your URL). https only, no template in the URL, no IP literal, never a gemmein.com host, no credentials in the URL. In gemmein dev, http to localhost is allowed |
start_run | tool (an AI tool's name, fixed and never a template), inputs? (an object of the tool's own declared input names to templated strings) | Starts a run on tool for the event's person, as if they called POST /ai/run/<tool>. Credits are held from that person, never from the relay. The run submits itself on whatever provider the tool names, including an agent behind an external pipeline. A saved record can start your agent with nobody present, or a Monday schedule can run a subscriber's tracker. A refusal from the run (unknown_tool, entitlement_required, credits_exhausted, …) is a definition-level failure: recorded on the event, never retried |
The ref
fulfil_product, refund_product, grant_plan and
revoke_plan are idempotent on ref, which must be the provider's
unique payment identifier. A ref already used by another purchase is refused
and audited. A ref you wrote that names nothing on the event is refused and
is not replaced. Only an absent ref falls back to
rly:<eventId>.
Which relay can fulfil or refund
fulfil_productfulfils only a product whose "How it's sold" names this relay, andgrant_plangrants only a plan whose "How it's sold" names this relay. The link is by name: renaming or deleting the relay stops fulfilment until a relay with that name exists again, and the product card shows it.refund_productcan run from any relay in the environment. It refunds only a purchase a relay fulfilled, for the event's person and the product it names.revoke_planfollows the grant, so it can run from any relay in the environment. It never ends a subscription billed through Stripe, which Stripe ends, and the event's result says so.- Saving a relay action, or a product's "How it's sold", against a relay that does not
exist in this environment answers 400
relay_missing.
Templates
String values in write_record.data, email_person's subject
and text, and grant_access.reason can carry a path in double braces:
{{event.a.b}} for the raw body, {{mapped.x}},
{{record.data.x}}, {{record.id}},
{{person.email}}, {{person.id}} and
{{tick.periodStart}}. A path that names nothing renders empty and adds a
warning to the event. An object renders as JSON. There are no expressions and no
filters. A template is refused in call_url.url and in an
entitlement.
Was this page helpful?
Thanks for telling us.
Thanks for telling us.
Last updated