`artifuncs.json`

Every tool repo has an artifuncs.json at its root. It declares the tool's interface: what type of tool it is, what inputs it takes, what outputs it produces, what settings users can tweak, and which external APIs it's allowed to call.

The file is read by the sandbox to render your tool's UI and validate its inputs and outputs. Invalid JSON blocks saving and publishing.

Minimal example

▸json

{
  "name": "Sum",
  "type": "INPUT_OUTPUT",
  "language": "PYTHON",
  "fields": {
    "input": {
      "a": { "type": "number", "default": 0 },
      "b": { "type": "number", "default": 0 }
    },
    "output": {
      "sum": { "type": "number" }
    }
  }
}

Top-level keys

Key	Required	Description
`name`	yes	Display name shown on the tool card.
`type`	yes	`INPUT_OUTPUT` or `IFRAME`. See below.
`language`	yes	`PYTHON`.
`layout`	no	`HORIZONTAL` (default) or `VERTICAL`. Controls how input and output panels stack.
`fields`	yes (for `INPUT_OUTPUT`)	Input and output field declarations. See Fields.
`settings`	no	User-tunable values that persist across runs but aren't part of the per-run input.
`userInstructions`	no	Free-text usage guidance shown to visitors above the tool form. See below.
`apis`	no	Allowlist of external HTTP APIs the tool may call.

`type`

INPUT_OUTPUT — The default. Your tool receives an input object, returns an output object. Inputs and outputs are rendered as forms from the fields block.
IFRAME — Your tool is a self-contained web page rendered in an iframe (URL configured via the General tab of the tool editor). fields are ignored.

The type is locked at tool creation and can't be changed.

`fields`

Two sub-blocks: input and output. Each maps a field name to a field declaration:

▸json

"fields": {
  "input": {
    "source": { "type": "text-field", "label": "Source", "default": "" }
  },
  "output": {
    "result": { "type": "text-field", "label": "Result" }
  }
}

The field name (e.g. source) is the key your code reads from input and writes to output. See the Fields reference for every supported type and option.

`settings`

Same shape as fields.input, but values live in a separate Settings panel and persist between runs. Use settings for things a user tweaks once and reuses (precision, API keys, default formats).

▸json

"settings": {
  "precision": { "type": "number", "label": "Decimal places", "default": 2 }
}

In your Python code, settings are available as the second argument to process:

▸python

def process(input, settings):
    return { "sum": round(input["a"] + input["b"], settings["precision"]) }

`userInstructions`

Optional free-text guidance for people using your tool. When set, it's shown in a "How to use" panel above the tool form on the public func page (/f/<handle>). Use it to explain what the tool expects, how to read the output, or any caveats.

▸json

{
  "name": "CSV Cleaner",
  "type": "INPUT_OUTPUT",
  "language": "PYTHON",
  "userInstructions": "Upload a CSV with a header row. Empty rows are dropped and columns are trimmed. Large files (>5 MB) may take a few seconds.",
  "fields": { "input": { "...": {} }, "output": { "...": {} } }
}

Line breaks in the string are preserved. It's plain text (not Markdown), so write it as you'd want it read.

`apis`

Tools run in a locked-down sandbox with no outbound network access by default. To call an external HTTP API, declare it here:

▸json

"apis": {
  "openai": { "domain": "api.openai.com" }
}

Each entry must point to a Trusted API the platform recognizes. APIs that aren't on the allowlist will be rejected during review.

Validation

artifuncs.json must be valid JSON. The IDE blocks save on parse errors.
name, type, language are required.
For INPUT_OUTPUT, fields.input and fields.output must exist and be objects (they can be empty {}).
Field names must be valid identifiers — letters, digits, and underscores only.
Field types must be one of the supported types. Unknown types render as an error placeholder.

Publishing runs the same checks plus a deeper review (see Publishing a tool).