Tool reference
Every tool works the same way through every interface:
- CLI:
opf <tool> key=value … - MCP:
<module>_<verb>, e.g.tasks_claim - HTTP:
POST /v1/tools/<tool>with a JSON body - Assistant:
aw.<module>.<verb>({…})
Read tools never change anything. Write tools need an idempotency key for safe retries and are subject to trust levels.
Agents
Section titled “Agents”agents.activity
Section titled “agents.activity”write Report what the calling agent is doing: running while a run is in progress, idle between runs. agents.list shows it with the time it changed, so a run stuck for hours stands out. opf worker reports it for you.
| Field | Type | Description | |
|---|---|---|---|
state |
string | required | running (a run started) or idle (it ended) |
note |
string | What the run is about or how it ended, e.g. a task ID or exit 0 |
agents.list
Section titled “agents.list”read List all agents with status and last-seen time.
No input.
agents.whoami
Section titled “agents.whoami”read Show the workspace, the calling agent’s identity and its trust levels for writing tools.
No input.
channels
Section titled “channels”channels.list
Section titled “channels.list”read List channels with their newest post and what you have not read yet (unread posts by others, and mentions of you).
No input.
channels.post
Section titled “channels.post”write Write in a channel: a post, a reply (reply_to) or a question (options). Everyone sees it; @name mentions count as unread for that person or agent.
| Field | Type | Description | |
|---|---|---|---|
channel |
string | required | Channel name, e.g. rechenzettel; a new name starts a channel |
text |
string | required | Markdown; @name mentions a person or agent |
options |
string[] | Makes the post a question with these answers to pick from | |
reply_to |
string | Id of the post this answers (same channel); answer a question with one of its options |
channels.read
Section titled “channels.read”read Read a channel, oldest first. Moves your read mark to the newest post returned unless keep_mark.
| Field | Type | Description | |
|---|---|---|---|
channel |
string | required | |
after |
integer | Only posts newer than this seq | |
before |
integer | Page back: posts older than this seq | |
keep_mark |
boolean | Don’t move your read mark | |
limit |
integer | Default 50, max 200 | |
unread |
boolean | Only posts after your read mark |
Collections
Section titled “Collections”coll.add
Section titled “coll.add”write Add one row (row) or several (rows). Fields must match the columns; returns the new ids.
| Field | Type | Description | |
|---|---|---|---|
collection |
string | required | |
row |
object | One row as an object: {column: value} | |
rows |
object[] | Several rows at once (max 500) |
coll.alter
Section titled “coll.alter”write Replace a collection’s columns (add, remove, reorder, retype). Existing rows are kept.
| Field | Type | Description | |
|---|---|---|---|
columns |
object[] | required | The full new column list. Values of removed columns stay stored but are hidden |
name |
string | required | |
if_version |
integer | Only change if the collection is at this version | |
title |
string | New title; empty keeps it |
coll.create
Section titled “coll.create”write Create a collection (a sheet) with its columns.
| Field | Type | Description | |
|---|---|---|---|
columns |
object[] | required | [{name, type: text|number|bool|date|json, label, formula}]; formula makes a computed column, e.g. “row.price * row.qty” |
name |
string | required | Lowercase name, e.g. expenses |
title |
string | Display title; defaults to the name |
coll.delete
Section titled “coll.delete”write Delete one row.
| Field | Type | Description | |
|---|---|---|---|
collection |
string | required | |
id |
string | required | |
if_version |
integer |
coll.drop
Section titled “coll.drop”write Delete a collection and all its rows. Agents need human approval by default.
| Field | Type | Description | |
|---|---|---|---|
name |
string | required |
coll.get
Section titled “coll.get”read Read one row by id, including computed columns.
| Field | Type | Description | |
|---|---|---|---|
collection |
string | required | |
id |
string | required |
coll.list
Section titled “coll.list”read List collections with their columns and row counts.
No input.
coll.query
Section titled “coll.query”read Read rows with optional equality filters, text search, sort and paging. Returns rows, total matches and columns.
| Field | Type | Description | |
|---|---|---|---|
collection |
string | required | |
limit |
integer | Default 100, max 1000 | |
offset |
integer | ||
search |
string | Case-insensitive text found in any value | |
sort |
string | Column to sort by; prefix - for descending, e.g. -amount. Default: oldest first | |
where |
object | Equality filters: {column: value}; all must match |
coll.schema
Section titled “coll.schema”read Show a collection’s columns, version and row count.
| Field | Type | Description | |
|---|---|---|---|
name |
string | required |
coll.update
Section titled “coll.update”write Change some fields of a row (partial update).
| Field | Type | Description | |
|---|---|---|---|
collection |
string | required | |
id |
string | required | |
set |
object | required | Fields to change; null clears a field. Other fields stay |
if_version |
integer | Only change if the row is at this version (409 returns the current row) |
Events
Section titled “Events”events.since
Section titled “events.since”read Read the event log after a cursor. Store the returned cursor and pass it next time to catch up after being offline.
| Field | Type | Description | |
|---|---|---|---|
actor |
string | Filter by agent name | |
cursor |
integer | Return events with seq greater than this; 0 = from the start | |
limit |
integer | Default 100, max 1000 | |
module |
string | Filter: kv, msg, task, inbox, agent, … | |
subject_prefix |
string | Filter by subject (key, task id, topic) prefix | |
timeout_seconds |
integer | Only for wait: long-poll timeout, default 30, max 300 |
events.wait
Section titled “events.wait”read Like events.since, but blocks until at least one matching event exists or the timeout passes.
| Field | Type | Description | |
|---|---|---|---|
actor |
string | Filter by agent name | |
cursor |
integer | Return events with seq greater than this; 0 = from the start | |
limit |
integer | Default 100, max 1000 | |
module |
string | Filter: kv, msg, task, inbox, agent, … | |
subject_prefix |
string | Filter by subject (key, task id, topic) prefix | |
timeout_seconds |
integer | Only for wait: long-poll timeout, default 30, max 300 |
feedback
Section titled “feedback”feedback.get
Section titled “feedback.get”read Read one feedback entry with status, note (the operator’s answer) and screenshot_url (GET it with the agent token). Personal fields (email, author, author_name, user_agent) only for people and the submitting agent.
| Field | Type | Description | |
|---|---|---|---|
id |
string | required | id from feedback.submit or feedback.list |
feedback.list
Section titled “feedback.list”read List feedback, newest first, filtered by app, author, status or kind; returns total for paging. Personal fields (email, author, author_name, user_agent) only for people and the submitting agent; others see has_email.
| Field | Type | Description | |
|---|---|---|---|
app |
string | Only this app | |
author |
string | Only this author (the app’s user id), e.g. for a user’s ‘my reports’ | |
kind |
string | fehler, idee or frage; empty = all | |
limit |
integer | Default 50, max 500 | |
offset |
integer | ||
status |
string | neu, angenommen, abgelehnt or live; empty = all |
feedback.submit
Section titled “feedback.submit”write Send user feedback from an app (bug, idea or question). Adds an entry with status ‘neu’ to collection ‘feedback’ (created on first use) and a triage task on the queue in kv feedback/queue (default coach). Returns id and status; status changes come back as messages on topic feedback.status.
| Field | Type | Description | |
|---|---|---|---|
kind |
string | required | fehler (bug), idee (idea) or frage (question) |
text |
string | required | What the user wrote, up to 5000 characters |
app |
string | Short app name, e.g. buero (lowercase, max 40); feedback.list filters by it | |
app_version |
string | Optional app version or build | |
author |
string | Optional opaque user id in the app, so the app can list a user’s own reports (personal: row only) | |
author_name |
string | Optional name the user signed with (personal: row only) | |
email |
string | Optional address to answer to (personal: row only, never in tasks, events or messages) | |
external_id |
string | Optional id in the app: sending the same external_id again returns the existing entry | |
page |
string | Page or URL the user was on | |
screenshot |
string | Optional PNG or JPEG, base64 (a data: URL works too), up to 2 MB; stored as file feedback/<id>.<ext> | |
user_agent |
string | Optional browser user agent (personal: row only) |
feedback.update
Section titled “feedback.update”write Set a feedback entry’s status (neu, angenommen, abgelehnt, live) and optionally the note (the answer the author reads). Emits feedback.status and sends a message on topic feedback.status to the agent that submitted it (correlation_id = id), so the app can tell its user. The hub sends no mail.
| Field | Type | Description | |
|---|---|---|---|
id |
string | required | id from feedback.submit or feedback.list |
status |
string | required | neu, angenommen, abgelehnt or live |
note |
string | The answer the author reads in the app; empty clears it, absent keeps it |
files.commit
Section titled “files.commit”write Point a path at content uploaded before (PUT /v1/blobs), as a new version. Used by streaming uploads and opf files push.
| Field | Type | Description | |
|---|---|---|---|
path |
string | required | |
sha256 |
string | required | Content already uploaded with PUT /v1/blobs |
content_type |
string | ||
if_version |
integer |
files.delete
Section titled “files.delete”write Delete a file. Its versions stay in the history for the retention period.
| Field | Type | Description | |
|---|---|---|---|
path |
string | required | |
if_version |
integer |
files.get
Section titled “files.get”read Read a small text file (up to 256 KB) inline. Larger or binary files: download with opf files get or GET /v1/files/<path>.
| Field | Type | Description | |
|---|---|---|---|
path |
string | required | |
version |
integer | An older version from files.history |
files.history
Section titled “files.history”read List the versions of a path, newest first (deletes have an empty sha256).
| Field | Type | Description | |
|---|---|---|---|
path |
string | required |
files.list
Section titled “files.list”read List a folder: its files and subfolders. With recursive=true, all files below the prefix, paged.
| Field | Type | Description | |
|---|---|---|---|
after |
string | Page cursor (recursive listings): the ‘next’ value of the previous call | |
limit |
integer | Default 200, max 1000 | |
prefix |
string | Folder to list, e.g. reports/2026/ (empty = top level) | |
recursive |
boolean | List all files below prefix instead of one folder level |
files.put
Section titled “files.put”write Write a small file (up to 1 MB) from text or base64. Every write is a new version.
| Field | Type | Description | |
|---|---|---|---|
path |
string | required | e.g. reports/2026/q3.md |
content |
string | Text content (up to 1 MB) | |
content_base64 |
string | Binary content, base64 (up to 1 MB); bigger files use the streaming upload | |
content_type |
string | Default: from the extension | |
if_version |
integer | Only write if the file is at this version; 0 = must not exist |
files.stat
Section titled “files.stat”read Show a file’s size, type, sha256 and version.
| Field | Type | Description | |
|---|---|---|---|
path |
string | required |
Functions
Section titled “Functions”fn.delete
Section titled “fn.delete”write Delete a function. Its run log stays for two weeks.
| Field | Type | Description | |
|---|---|---|---|
name |
string | required |
fn.get
Section titled “fn.get”read Show a function with its code.
| Field | Type | Description | |
|---|---|---|---|
name |
string | required |
fn.list
Section titled “fn.list”read List functions (triggers and jobs) with their status and last run.
No input.
fn.put
Section titled “fn.put”write Create or update a function. New code needs human approval for agents by default.
| Field | Type | Description | |
|---|---|---|---|
code |
string | required | JavaScript function body. Gets event (trigger: the row change or the message) and input (manual run); calls aw.<module>.<verb>(input); log(…) writes to the run log; return a value as the result |
kind |
string | required | trigger (runs on collection changes or messages) or job (runs on a schedule) |
name |
string | required | Lowercase name, e.g. notify-done |
collection |
string | trigger: the collection to watch | |
on |
string[] | collection trigger: add, update, delete (default all) | |
schedule |
string | job: cron in UTC, e.g. “0 7 * * ”, “/15 * * * *”, “@hourly”, “@every 10m” | |
topic |
string | trigger: run on every message sent to this topic instead, e.g. ads.set_budget; a trailing * matches a prefix (ads.*) |
fn.run
Section titled “fn.run”read Run a function now (any kind) and return its result and log.
| Field | Type | Description | |
|---|---|---|---|
name |
string | required | |
input |
JSON | Passed as input; for a trigger also as the event, to test it with a sample event |
fn.runs
Section titled “fn.runs”read Show a function’s recent runs with logs, results and errors.
| Field | Type | Description | |
|---|---|---|---|
name |
string | required | |
limit |
integer | Default 20, max 200 |
fn.status
Section titled “fn.status”write Pause or resume a function.
| Field | Type | Description | |
|---|---|---|---|
name |
string | required | |
status |
string | required | active or paused |
inbox.ask
Section titled “inbox.ask”write Ask a human a question. Returns request_id immediately; get the answer with inbox.wait, or later as a message on topic inbox.resolved (correlation_id = request_id).
| Field | Type | Description | |
|---|---|---|---|
title |
string | required | The question for the human |
body |
string | Context, markdown allowed | |
correlation_id |
string | ||
expires_in_seconds |
integer | Default 24h | |
options |
string[] | Answer choices; empty means yes/no plus free text |
inbox.list
Section titled “inbox.list”read List inbox items, newest first. Agents see their own items; the human and the assistant see all.
| Field | Type | Description | |
|---|---|---|---|
kind |
string | question, approval, notify, registration; empty = all | |
limit |
integer | Default 50, max 500 | |
status |
string | open (default), answered, approved, rejected, expired, dismissed, withdrawn, or ‘all’ |
inbox.notify
Section titled “inbox.notify”write Leave an informational note for the human; no answer expected.
| Field | Type | Description | |
|---|---|---|---|
title |
string | required | |
body |
string | ||
correlation_id |
string |
inbox.wait
Section titled “inbox.wait”read Wait for a human to answer a question or decide an approval. Returns the item; status stays ‘open’ on timeout.
| Field | Type | Description | |
|---|---|---|---|
id |
string | required | request_id from inbox.ask or a pending tool call |
timeout_seconds |
integer | Long-poll timeout, default 30, max 300 |
inbox.withdraw
Section titled “inbox.withdraw”write Close your own open question, approval or note (inbox.notify) because it was answered elsewhere (e.g. the human answered in chat) or is outdated, so the human doesn’t see it twice. Status becomes ‘withdrawn’ with your answer; no inbox.resolved message follows.
| Field | Type | Description | |
|---|---|---|---|
answer |
string | required | Why it is closed, usually the answer the human gave elsewhere, e.g. “Sparrechner (answered in chat)” |
id |
string | required | id of your own open question, approval or note |
Key-value
Section titled “Key-value”kv.cas
Section titled “kv.cas”write Compare-and-set: write only if the key is at if_version.
| Field | Type | Description | |
|---|---|---|---|
if_version |
integer | required | Expected current version; 0 = key must not exist |
key |
string | required | |
value |
JSON | required | Any JSON value |
kv.delete
Section titled “kv.delete”write Delete a key, optionally guarded by if_version.
| Field | Type | Description | |
|---|---|---|---|
key |
string | required | |
if_version |
integer |
kv.get
Section titled “kv.get”read Read one key with its value and version.
| Field | Type | Description | |
|---|---|---|---|
key |
string | required |
kv.list
Section titled “kv.list”read List keys by prefix, sorted. When more exist, ‘next’ is the cursor for the following page.
| Field | Type | Description | |
|---|---|---|---|
after |
string | Page cursor: the ‘next’ value of the previous call | |
limit |
integer | Default 100, max 1000 | |
prefix |
string | Only keys starting with this |
kv.set
Section titled “kv.set”write Write a key. Pass if_version to guard against concurrent changes (409 conflict returns the current entry).
| Field | Type | Description | |
|---|---|---|---|
key |
string | required | |
value |
JSON | required | Any JSON value |
if_version |
integer | Only write if the current version matches; 0 = key must not exist |
kv.watch
Section titled “kv.watch”read Block until keys under prefix change after cursor; returns the kv events.
| Field | Type | Description | |
|---|---|---|---|
cursor |
integer | Event cursor; use the returned cursor for the next call | |
prefix |
string | Key or key prefix to watch | |
timeout_seconds |
integer | Default 30, max 300 |
mail.get
Section titled “mail.get”read Read one mail: text, HTML (cut at 256 KB), the links in it (e.g. a confirmation or reset link), references and attachments (GET their url with the agent token, or opf files get <path>).
| Field | Type | Description | |
|---|---|---|---|
id |
string | required | id from mail.list (or a Message-ID) |
mail.list
Section titled “mail.list”read List the workspace’s mail, newest first: received (kind support, info, test) and sent (kind sent), without text. Filter by to, from, kind, since or thread. Test sign-up, invite and reset mails with an address test-<workspace>-<anything>@inbox.operforms.com, then read the mail with mail.get.
| Field | Type | Description | |
|---|---|---|---|
from |
string | Only mail from this address (or part of it) | |
kind |
string | support, info, test or sent; empty = all | |
limit |
integer | Default 50, max 500 | |
since |
string | Only mail stored at or after this time (RFC 3339 or a date) | |
thread |
string | Only this conversation (the thread from mail.list or mail.get) | |
to |
string | Only mail to this address (or part of it, e.g. test-shop-) |
mail.send
Section titled “mail.send”write Send a mail through Brevo from one of the workspace’s support or info addresses. Needs a person’s approval (trust ask), unless every recipient is a test address @inbox.operforms.com. The sent mail is stored with kind sent and status sent, or failed with the error.
| Field | Type | Description | |
|---|---|---|---|
from |
string | required | A support or info address of this workspace |
text |
string | required | Plain text body |
to |
string[] | required | Recipients |
cc |
string[] | Copy to | |
html |
string | Optional HTML body | |
in_reply_to |
string | Answer this mail (id from mail.list or a Message-ID): sets In-Reply-To and References and keeps the thread | |
subject |
string | Subject; empty with in_reply_to: Re: <subject of that mail> |
Messages
Section titled “Messages”msg.ack
Section titled “msg.ack”write Acknowledge messages so they are not delivered again.
| Field | Type | Description | |
|---|---|---|---|
ids |
string[] | required | Message ids to acknowledge |
msg.pull
Section titled “msg.pull”read Fetch unacked messages addressed to you or broadcast. Pulled messages are hidden for visibility_seconds, then delivered again until msg.ack; ‘delivery’ > 1 marks a redelivery. Dedupe by id.
| Field | Type | Description | |
|---|---|---|---|
limit |
integer | Default 50, max 500 | |
topics |
string[] | Only these topics; empty = all | |
visibility_seconds |
integer | Hide pulled messages from further pulls for this long (default 60, max 3600, 0 = don’t hide); they come back until acked | |
wait_seconds |
integer | Long-poll up to this long when nothing is pending, max 300 |
msg.send
Section titled “msg.send”write Send a message to an agent or broadcast on a topic. Delivery is at-least-once until the recipient acks.
| Field | Type | Description | |
|---|---|---|---|
correlation_id |
string | Ties messages to a task or thread | |
payload |
JSON | Any JSON value | |
schema |
string | Payload schema, e.g. report.ready/v1 | |
to |
string | Recipient agent; empty = broadcast to everyone pulling the topic | |
topic |
string | Thread/topic; defaults to ‘direct’ when ‘to’ is set | |
type |
string | What happened, e.g. report.ready |
pages.delete
Section titled “pages.delete”write Delete a wiki page. Its versions stay in the history and in the event log.
| Field | Type | Description | |
|---|---|---|---|
slug |
string | required | |
if_version |
integer |
pages.get
Section titled “pages.get”read Read a wiki page with its Markdown body.
| Field | Type | Description | |
|---|---|---|---|
slug |
string | required | |
version |
integer | An older version from pages.history; default the current one |
pages.history
Section titled “pages.history”read List the versions of a page (newest first) with author and time.
| Field | Type | Description | |
|---|---|---|---|
slug |
string | required |
pages.list
Section titled “pages.list”read List wiki pages (slug, title, version), sorted by slug; bodies are not included. When more exist, ‘next’ is the cursor for the following page.
| Field | Type | Description | |
|---|---|---|---|
after |
string | Page cursor: the ‘next’ value of the previous call | |
limit |
integer | Default 200, max 1000 | |
prefix |
string | Only slugs starting with this, e.g. ops/ |
pages.put
Section titled “pages.put”write Create or update a wiki page (full replace). Every version is kept; a 409 conflict returns the current page.
| Field | Type | Description | |
|---|---|---|---|
body |
string | required | Markdown; link other pages with [[slug]] or [[slug|text]]. Live data from collections: a fenced code block whose info string is kpi, chart line or chart bar, with one ‘key: value’ per line (collection, where e.g. run=max, x, y, series, group, lines e.g. 250 Goal, markers, sort, show e.g. mrr MRR €, compare); see opf guide |
slug |
string | required | Lowercase path like ops/runbook |
if_version |
integer | Only write if the page is at this version; 0 = page must not exist. Use it to avoid overwriting someone else’s edit | |
title |
string | Defaults to the current title, or the slug for a new page |
pages.search
Section titled “pages.search”read Find pages whose title or body contains the text; returns slugs with a snippet.
| Field | Type | Description | |
|---|---|---|---|
query |
string | required | Case-insensitive text to find in titles and bodies |
limit |
integer | Default 20, max 100 |
tasks.claim
Section titled “tasks.claim”write Claim a task with a lease so no other agent works on it. Returns {task: null} when nothing is open.
| Field | Type | Description | |
|---|---|---|---|
id |
string | Claim this task; otherwise the most important, then oldest open task on the queue whose after tasks are done | |
lease_seconds |
integer | Default 300, max 3600. Renew with tasks.heartbeat | |
queue |
string | Default ‘default’ |
tasks.complete
Section titled “tasks.complete”write Mark a task you hold as done.
| Field | Type | Description | |
|---|---|---|---|
id |
string | required | |
result |
JSON | Any JSON value |
tasks.create
Section titled “tasks.create”write Create a task on a queue for any agent to claim. Queue “people” is the stack of tasks for humans: they see it under My tasks, most important first. With after, it waits until those tasks are done (e.g. build steps 1/3, 2/3, 3/3).
| Field | Type | Description | |
|---|---|---|---|
title |
string | required | |
after |
string[] | IDs of tasks (this workspace) that must be done first; until then nobody can claim this one | |
assignee |
string | Optional: one person (@name) or agent who should do it | |
correlation_id |
string | ||
description |
string | ||
payload |
JSON | Any JSON value | |
priority |
integer | 1 (most important) to 5; default 3. Claims take the most important first | |
queue |
string | Default ‘default’ |
tasks.fail
Section titled “tasks.fail”write Report that a task you hold failed; with retry=true it goes back to open.
| Field | Type | Description | |
|---|---|---|---|
error |
string | required | |
id |
string | required | |
retry |
boolean | Put the task back on the queue instead of failing it |
tasks.get
Section titled “tasks.get”read Read one task.
| Field | Type | Description | |
|---|---|---|---|
id |
string | required |
tasks.heartbeat
Section titled “tasks.heartbeat”write Extend the lease on a task you hold. A 409 means you lost it.
| Field | Type | Description | |
|---|---|---|---|
id |
string | required | |
lease_seconds |
integer | Default 300, max 3600 |
tasks.list
Section titled “tasks.list”read List tasks, most recently updated first (or by priority).
| Field | Type | Description | |
|---|---|---|---|
limit |
integer | Default 100, max 1000 | |
queue |
string | ||
sort |
string | updated (default, most recent first) or priority (most important first) | |
status |
string | open, claimed, done, failed; empty = all |
tasks.prioritize
Section titled “tasks.prioritize”write Change the priority of an open or claimed task, e.g. to reorder a person’s stack.
| Field | Type | Description | |
|---|---|---|---|
id |
string | required | |
priority |
integer | required | 1 (most important) to 5 |
tasks.update
Section titled “tasks.update”write Change title, description, priority or after of an open task instead of closing and recreating it; id and history stay. Claimed, done or failed tasks cannot be changed (409).
| Field | Type | Description | |
|---|---|---|---|
id |
string | required | |
after |
string[] | New list of tasks that must be done first (replaces it; [] removes all), e.g. when one of them failed | |
description |
string | New description; omit to keep it, empty clears it | |
if_version |
integer | Only change if the task is at this version (409 conflict returns the current task) | |
priority |
integer | 1 (most important) to 5; omit to keep it | |
title |
string | New title; omit to keep it |
tasks.wait
Section titled “tasks.wait”read Wait until the queue has a task to claim (long poll: open, and its after tasks done), then claim it with tasks.claim. Returns {ready: true} as soon as there is one, {ready: false} after wait_seconds. Workers use it instead of polling.
| Field | Type | Description | |
|---|---|---|---|
queue |
string | Default ‘default’ | |
wait_seconds |
integer | Wait up to this long for an open task, default 30, max 300 |
usertests
Section titled “usertests”usertests.close
Section titled “usertests.close”write End a user test early: its link stops accepting submissions. Submissions already made stay.
| Field | Type | Description | |
|---|---|---|---|
code |
string | required |
usertests.create
Section titled “usertests.create”write Create a user-test link (Nutzertest): a stranger opens it on the phone without an account, consents, tries a task on the product and records spoken feedback (transcribed locally, audio deleted) or writes it, plus short answers. Each submission becomes a row in collection ‘nutzertest’ and an analysis task on queue (via queue ‘transkription’ when there is audio). Returns the link to hand out.
| Field | Type | Description | |
|---|---|---|---|
task |
string | required | Instructions for the tester (Markdown), e.g. what to find out on the page |
title |
string | required | Short name, e.g. ‘Sparplan-Rechner verstehen’ |
url |
string | required | Product page the tester tries (http or https) |
days |
integer | Validity in days, default 14, max 90 | |
lang |
string | Language of the tester page: de (default) or en | |
max_submissions |
integer | Default 10, max 100 | |
questions |
string[] | Optional short free-text questions asked after the task (max 10) | |
queue |
string | Queue for the analysis task; default ‘coach’ | |
record |
boolean | Ask for spoken feedback (default true); written feedback is always possible |
usertests.list
Section titled “usertests.list”read List user tests (newest first) with their link, state and number of submissions.
| Field | Type | Description | |
|---|---|---|---|
state |
string | open, closed, expired or full; empty = all |
Workspace
Section titled “Workspace”workspace.apply_template
Section titled “workspace.apply_template”write Set up this workspace from a template: creates missing collections, columns, pages, functions, kv keys, trust rules and agent invites. Existing pages and functions are kept; ones that differ from the template are listed under differs (update_pages / update_functions replace them). Rows, trust rules and pages owned by people are never overwritten; nothing is deleted. Agents need human approval.
| Field | Type | Description | |
|---|---|---|---|
template |
string | required | Template name, e.g. produkt (see workspace.templates) |
update_functions |
boolean | Replace existing template functions that differ | |
update_pages |
boolean | Replace existing template pages that differ (never pages owned by people); the old version stays in pages.history |
workspace.claim_link
Section titled “workspace.claim_link”write While nobody owns this workspace yet, create the one-time link the human uses to claim it (sign up with a passkey). Show the link to your human.
No input.
workspace.templates
Section titled “workspace.templates”read List the templates a workspace can be set up from (workspace.apply_template).
No input.