Docs

The @deploy decorator

Every option @deploy takes: name, title, description, secrets, timeout, schedule and next.

@deploy marks a function as something your team can run. It works bare or with options:

from callables import deploy


@deploy
def ping() -> str:
    return "pong"


@deploy(
    title="Closed deals",
    secrets=["CRM_TOKEN"],
    timeout=120,
)
def closed_deals(region: str = "NA", min_value: int = 0) -> list[dict]:
    """Deals closed in a region, newest first.

    Pulls from the CRM; amounts are in USD.
    """
    ...

The person running a function can't see its code. Everything they see comes from the decorator, the docstring, the parameter names and types, and the return value, so write those for them.

Options

Option	Default	What it does
`name`	the function's name	The function's identity on the platform
`title`	the name as a sentence	The heading on its card and page
`description`	the docstring's first paragraph	One line about what it does
`secrets`	none	Environment variables injected at run time
`timeout`	`300`	Seconds before the run is stopped, up to `900`
`schedule`	none	A cron expression in UTC, for a schedule kept in code
`next`	none	Actions offered on each result row

name

The function's identity. Run history, sharing and schedules belong to it. Changing the name creates a new function, and the old one's history and schedules stay behind. If you rename the Python function, pass the old name to keep its identity:

@deploy(name="closed_deals")
def deals_closed_by_region(region: str = "NA") -> list[dict]: ...

Inside a group, the full name is <group>.<name>, such as billing.refund.

title and description

title defaults to the name with underscores as spaces, so closed_deals shows as "Closed deals". description defaults to the first paragraph of the docstring. Write one plain sentence about what the function does for the person running it, not how it works.

secrets

A list of environment variable names. Builders set the values in the web app, and they're injected when the function runs. Read them inside the function:

import os

token = os.environ["CRM_TOKEN"]

A declared secret that nobody has set doesn't block the run. The variable is simply missing, and builders see a "missing secrets" warning. See secrets.

timeout

Seconds before the run is stopped. The default is 300 (5 minutes) and the maximum is 900 (15 minutes). A higher value is capped at 900, and call check warns about it.

schedule

A cron expression in UTC, such as "0 9 * * MON". The schedule is created on push and removed when you delete the line. Every input needs a default. You usually don't need this: anyone can add a schedule in the web app, with a time zone. See schedules.

Actions offered on each row of the result, with their inputs filled in from the row. See flows.

Errors

Raise exceptions with messages written for the person running the function. They see the message, such as ValueError: No deals found for EMEA since 2026-01-01, but never the traceback. For bad input, raise ValueError and say which field to change. Builders see the full traceback on the run page.

Coding agents

Inputs