Script Development / Export Function DFF.API

DFF.API(...) returns a decorator that exposes the decorated top-level function externally, allowing it to be invoked via the Func API, Cron Job, MCP, function page, or debug execution.

Only entry functions that need to be invoked beyond ordinary Python imports should use @DFF.API(...); private helper functions do not need to add this decorator.

In the same Script, decorated function names must be unique; duplicate names will cause the Script to fail to load.

The detailed parameter list is as follows:

Parameter	Type	Required / Default Value	Description
title	str	None	Display name of the exported function, mainly used for interface display.
require_api_auth	bool	False	Requires API Auth when the Func is exposed via Func API.
category	str	"general"	The category to which the function belongs, defaults to "general". Mainly used for categorization/filtering of the function list.
tags	list	None	Function tag list, mainly used for categorization/filtering of the function list.
tags[#]	str	Required	Function tag.
timeout	int / dynamic reference	None	Function timeout duration. Unit: seconds, value range 1 ~ 3600.
expires	int / dynamic reference	None	Maximum queue wait duration. Unit: seconds, value range 1 ~ 86400.
cache_result	int	None	Duration for caching result data. Unit: seconds, use a positive integer; None or 0 means no caching.
queue	int / dynamic reference	None	User Worker queue number.
fixed_cron_expr	str(Cron-format)	None	When the function is executed by a Cron Job, force the use of the specified five-segment Cron expression.
fixed_delayed_cron_job	int / list[int]	None	Force the Cron Job to use the specified delayed execution seconds
delayed_cron_job	int / list[int] / dynamic reference	None	Default delayed execution seconds used when the Cron Job does not configure its own delay.
mcp_annotations	dict	None	Standard MCP tool behavior hints and confirmationHint extension.
integration	str	None	Built-in integration, optional signIn or autoRun.
auto_run	dict	None	Auto-run configuration; also sets integration='autoRun'.
is_hidden	bool	False	Hide from normal Func discovery results.
custom	JSON-serializable value	None	Custom metadata.
custom_json	str(JSON)	None	Custom metadata encoded as JSON text.
custom_yaml	str(YAML)	None	Custom metadata encoded as YAML text.

See below for detailed explanations of each parameter:

Parameter title

The function title is convenient for display in various DataFlux Func operation interfaces / documentation.

@DFF.API('My Function')
def my_func():
    pass

Parameter require_api_auth

When a Func is exposed externally via the Func API, you can set require_api_auth=True to require callers to authenticate via API Auth.

@DFF.API('My Function', require_api_auth=True)
def my_func():
    pass

After the Func API is published, callers will depend on the function's input and return structure, so both should remain stable.

Parameter category / tags

The category and tag list to which the function belongs; they do not participate in or control the function's execution, and are mainly used for convenient classification and management of functions. They can be used together or separately.

At runtime, the category and tags are exposed via _DFF_FUNC_CATEGORY and _DFF_FUNC_TAGS, respectively. They are descriptive metadata only and cannot be used to establish identity or permission boundaries.

@DFF.API('My Function', category='demo', tags=['tag1', 'tag2'])
def my_func():
    pass

Once specified, the function list can be filtered by specifying filter parameters, for example:

# Filter by category
GET /api/v1/func-list?category=demo

# Filter by tags (specifying multiple tags means "include all")
GET /api/v1/func-list?tags=tag1,tag2

Parameter timeout

To protect the system, all functions running in DataFlux Func have a runtime limit and are not allowed to run indefinitely. When timeout is not configured, different invocation methods have different default values.

Invocation Method	timeout Default Value
Synchronously executed Func API	35
Asynchronously executed Func API	3600
Cron Job	35

@DFF.API('My Function', timeout=30)
def my_func():
    pass

For functions executed in the DataFlux Func editor, the system ignores the timeout configuration and sets it to a fixed 60 seconds.

Danger

The maximum configurable value for timeout is 3600 seconds (i.e., 1 hour), in order to protect the system. If you carelessly set the timeouts of all functions to the maximum, you may fail to promptly discover problems in code writing and design, and may also cause queue congestion and other issues.

Therefore, the timeout parameter should be set based on actual requirements. A large number of long-running Func API requests can cause task queue congestion; use caching techniques when necessary.

Warning

An HTTP interface with a response time exceeding 3 seconds can be considered very slow. Be careful not to configure meaningless, excessively long timeouts for functions.

At the same time, the browser itself also limits the maximum request duration (e.g., 4 minutes in Chrome), so setting an excessively long timeout in the Func API is meaningless

Parameter expires / queue

expires is used to limit the maximum waiting time of a task in the queue, with a value range of 1 ~ 86400 seconds. After the waiting time is exceeded, the task will not start executing; it differs from timeout, which limits the actual runtime duration.

queue is used to specify the user Worker queue number. The available numbers depend on the current DataFlux Func Worker configuration.

Parameter cache_result

DataFlux Func has built-in API-level caching. With the cache parameter specified, when the exact same function and parameters are called, the system directly returns the cached result.

cache_result should only use positive integers for seconds; passing None or 0 disables caching.

@DFF.API('My Func', cache_result=30)
def my_func():
    pass

Once the cache is hit, the API directly returns the result, and the function is not actually executed.

After a cache hit, the returned HTTP headers include the following marker:

X-Dataflux-Func-Cache: Cached

Parameter fixed_cron_expr

For some functions that will be used in Cron Jobs, the function author may have requirements for the frequency of automatic execution. In this case, you can specify this parameter to fix the Cron Jobs belonging to this function to the specified five-segment Cron expression. This parameter should only be used when the scheduling frequency must be controlled by the Script; otherwise, it should be controlled by the Cron Job configuration.

@DFF.API('My Func', fixed_cron_expr='*/5 * * * *')
def my_func():
    pass

Parameter fixed_delayed_cron_job / delayed_cron_job

For some functions used in Cron Jobs, the function author may wish to run at a more precise time (e.g., delayed by 10 seconds on the basis of * * * * *). fixed_delayed_cron_job overrides the delay configured by the Cron Job itself; delayed_cron_job is used as a default only when the Cron Job has no delay configured. Both accept a single number of seconds or an array of seconds; when an array is passed, the function runs after each specified delay is reached.

Delayed execution only guarantees that the function will not run earlier than the specified time; it does not guarantee that the function will run immediately when the specified time is reached.

These parameters are not applicable to situations where long-running Cron Jobs exist, regardless of whether these long-running tasks are related to delayed execution.

@DFF.API('My Func', fixed_delayed_cron_job=10)
def my_func():
    '''
    Execute with a 10-second delay
    '''
    pass

@DFF.API('My Func 2', delayed_cron_job=[0, 10])
def my_func_2():
    '''
    Execute with a delay of 0 and 10 seconds, running 2 times in total
    '''
    pass

Dynamic References

delayed_cron_job, timeout, expires, and queue support dynamic references returned using the following methods:

• DFF.ENV.ref(key, default=None)
• DFF.STORE.ref(key, scope=None, default=None)
• DFF.CACHE.ref(key, scope=None, default=None)

DFF.STORE.ref(...) and DFF.CACHE.ref(...) use REF when scope is omitted. Dynamic references are resolved when Func metadata is consumed; if the resolved result is invalid, it is ignored and does not change the decorator declaration.

@DFF.API(
    'Environment-controlled task',
    timeout=DFF.ENV.ref('FUNC_TIMEOUT', default=35),
    queue=DFF.ENV.ref('FUNC_QUEUE', default=1),
)
def environment_controlled():
    return 'ok'

Parameter mcp_annotations

When a Func is exposed directly as an MCP tool, tool behavior can be declared via mcp_annotations. MCP2 list-func and MCP3 search-func also return the standard Hints through the annotations metadata.

Hint	Type	Description
readOnlyHint	bool	The tool does not modify the environment
destructiveHint	bool	Tools that modify the environment may cause destructive changes
idempotentHint	bool	Repeated calls with the same parameters have no additional effect
openWorldHint	bool	The tool may interact with external entities
confirmationHint	bool / str	DataFlux Func extension that requires the Agent to obtain user confirmation before calling

The values of the four standard Hints must be boolean. Only explicitly passed standard Hints are written to annotations; an empty dictionary does not produce annotations.

confirmationHint is not written to the standard MCP annotations. When True is passed, the following default prompt is appended directly on the next line of the Func description, with no blank line in between:

**The AI Agent MUST obtain the user's explicit confirmation before calling this tool. The AI Agent MUST NOT call this tool without that explicit confirmation.**

When False is passed, nothing is appended; when a string is passed, that string is appended as-is on the next line to replace the default prompt. This is only an instruction provided to the Agent, not confirmation or authorization control enforced by the server.

@DFF.API(
    'Read local user',
    mcp_annotations={
        'readOnlyHint': True,
        'openWorldHint': False,
        'confirmationHint': True,
    },
)
def read_local_user(user_id):
    return {'user_id': user_id}

Parameter integration / auto_run / is_hidden

integration is used to declare built-in integrations, with valid values signIn or autoRun. This parameter should only be set when the corresponding integration behavior is explicitly required.

integration='signIn'

signIn is an installation-level login entry. At runtime, username and password are passed to the Func; returning a falsy value or empty value rejects the login, returning True uses the username as the external identity, returning a string or number uses that value as the external identity, and returning a dictionary can also provide identity, display name, and email information.

Danger

After a successful login, a local user with the administrator role is currently created or updated, so this Func belongs to the administrator trust boundary. It should only be responsible for authentication and must not record, persist, return, or print the passed credentials; failure messages must not contain credential content, and it should only return the minimal user information required for authentication.

Login credentials are also Func parameters and may be retained in task records or self-monitoring data depending on installation settings. Before enabling the login integration, you should first check the relevant settings.

Parameter auto_run

auto_run is used to configure the automatic run entry, and also sets integration='autoRun'. The following specification keys are supported:

Key	Description
cronExpr	Triggered by Cron expression
onSystemLaunch	Triggered on system launch
onScriptPublish	Triggered after Script publication

These triggers do not provide Func parameters, so automatic run entries cannot require positional or keyword parameters. onScriptPublish only starts after the published Script data synchronization completes, and executes the just-published code; if synchronization fails, the automatic run is skipped.

@DFF.API('Automatic run entry', auto_run={'onSystemLaunch': True, 'onScriptPublish': True})
def auto_run_entry():
    return 'ok'

Parameter is_hidden

Setting is_hidden=True can hide the Func from normal Func discovery results. This parameter should only be used when an entry explicitly needs to be hidden.

Parameter custom / custom_json / custom_yaml

These three parameters are used to set custom metadata: custom accepts a JSON-serializable value, custom_json accepts JSON text, and custom_yaml accepts YAML text. Only one of these parameters should be passed at a time.