Configuration

Everything lives in the plugin instance's config: block. Apiary validates it against the manifest's JSON Schema before the plugin is ever spawned, so apiary validate catches mistakes without running anything.

Top level

Key	Type	Default	Meaning
state_file	string	required	Absolute path recording which occurrences have been emitted. See the note below.
timezone	string	UTC	Default IANA timezone for routines that do not name one.
max_per_poll	int	5	Cap on occurrences emitted per poll, across all routines.
routines	list	required	At least one routine.

state_file must be absolute

A plugin runs with its own install directory as the working directory, not your project root. A relative path resolves next to the binary, where you will not think to look for it — and where a reinstall may wipe it.

timezone defaults to UTC, not the host's local zone

So the same config fires at the same instant on every machine.

A routine

Key	Type	Default	Meaning
id	string	required	Names the routine. Cannot contain @ or whitespace — the item id is <id>@<instant>.
schedule	string	required	5-field cron, or @daily / @hourly / @weekly / @every 30m.
timezone	string	top-level	Overrides the default for this routine.
title	string	routine: <id>	The work item's title.
description	string	generated	The work item's description.
labels	list	[]	Extra labels. routine:<id> is always added.
type	string	—	Maps to the item's type, matchable in a trigger.
priority	string	—	Maps to the item's priority.
catch_up	bool	false	Emit occurrences missed during downtime. See How it works.
enabled	bool	true	Set false to park a routine without deleting its cursor.

Changing a routine's id starts a fresh occurrence history — the old cursor is pruned on the next poll and the new id registers a floor, emitting nothing until its next scheduled instant.

Schedule syntax

Standard five-field cron: minute, hour, day-of-month, month, day-of-week.

0 3 * * *      every day at 03:00
*/15 * * * *   every 15 minutes
0 9 * * 1      Mondays at 09:00
@daily         midnight
@every 30m     every 30 minutes from the daemon's start

Seconds are deliberately not supported. A routine dispatches an agent run, and the plugin is only consulted on the source's poll_interval, so sub-minute precision would be a promise the transport cannot keep. A six-field expression is rejected rather than silently reinterpreted.

Matching a routine in a workflow

workflows:
  - id: dependency-audit
    trigger:
      once: true
      match:
        source: routines
        labels: ["routine:nightly-dep-audit"]

Always set once: true. See Limits.

Poll interval

Set the source's poll_interval to the resolution you need. It bounds how late an occurrence can fire: with poll_interval: 60s, a 03:00 routine dispatches somewhere in 03:00–03:01. There is no benefit to polling faster than your tightest schedule.