> For the complete documentation index, see [llms.txt](https://docs.fastn.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fastn.ai/build/workflows/the-editor.md).

# The editor

The workflow editor walked through tab by tab, plus the configuration panel reference.

<figure><img src="https://1255842839-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3iSr2Tx8FvvuoLPncziH%2Fuploads%2Fgit-blob-cc36172e3580d7a2564f38e635ed98adb7065cad%2Fworkflow-editor.jpg?alt=media" alt="The workflow editor with code editing enabled: a Configuration panel on the left with Name and Slug fields, workflow.js in the middle labelled JavaScript · export default async function(ctx), and the Test panel on the right showing ctx.input, ctx.headers, Use contract, a Live selector and Run Live"><figcaption><p>The editor with code editing enabled, Configuration left, <code>workflow.js</code> centre, the tool tabs right.</p></figcaption></figure>

Opening a workflow (**Create workflow**, or **Edit** from a row's `⋯` menu), drops you into a drawer with **Configuration** on the left and the tool tabs on the right. Whether there is a code column between them depends on your workspace.

{% hint style="warning" %}
**Code editing is switched off in almost every workspace.** It is enabled only for the parent organisation, so unless you are working there, you will not see the middle column at all: the editor shows Configuration and the tool tabs, and the banner reads:

> Code editing is switched off for this workspace. Workflows here are generated and updated by the AI builder. It can be switched on if you want to write workflow code yourself; ask fastn to enable it.

Everything else on this page still applies. You change a workflow's behaviour by talking to the [agent](/build/agent.md) instead of typing into the file, and you still configure, test, wire connectors, edit the contract, publish and deploy exactly as described below. **If you want to write workflow code yourself, ask fastn to switch it on.**
{% endhint %}

The walkthrough below assumes the code column is present. This is roughly the order you move through it.

{% stepper %}
{% step %}

#### Set up Configuration

Under **Identity**, give it a **Name** (required) and, on a new workflow, a **Slug**: the slug is fixed once the workflow exists, so choose it deliberately. **Description** is free text. Under **Execution**, pick an **Execution tier**: `Instant` runs synchronously and caps at 30s, `Standard` returns `202` and runs up to 15 min, `Long` returns `202` and runs up to 36 h. The **Execution timeout** slider is then constrained to that tier.

Full ranges and defaults are in the Configuration panel reference below.
{% endstep %}

{% step %}

#### Decide what happens when a run fails

**Retry policy** is off by default; turning it on exposes **Max attempts**, **Initial interval (ms)**, **Backoff coefficient** and **Max interval (ms)**. It only retries transient failures: code errors, data errors and out-of-memory never retry. **Escalate on timeout** is a separate toggle that retries one tier up on a timeout, and is hidden on the `Long` tier.
{% endstep %}

{% step %}

#### Write the function

The middle column is one `<slug>.js` file exporting `export default async function (ctx)`. You reach the request through `ctx.input` and `ctx.headers`, and connected systems through `ctx.connectors` and `fastn.*`. A new workflow is scaffolded for you:

```javascript
export default async function(ctx) {
  const { input, headers } = ctx;
  // Your workflow logic here
  return { result: "Hello from workflow!", input };
}
```

**This step is the one that does not apply in most workspaces.** With code editing off (the default everywhere but the parent organisation), the file is generated and updated by the AI builder, and you describe the change you want to the [agent](/build/agent.md) rather than editing it here. Skip to the next step; everything from there on is identical.
{% endstep %}

{% step %}

#### Test it: `Test` tab

Put a body in the `ctx.input` editor and headers in `ctx.headers`, or press **Use contract** to fill the input from the declared contract. Pick what the run actually touches (`Live`, `Partial Mock` or `Fully Mock`), then **Run Live** (or **Run**).
{% endstep %}

{% step %}

#### Check the wiring: `Connectors` tab

Every `fastn.connectors.X.Y(…)` call in your code is extracted here each time you save, so this tab is a readout of what the workflow actually talks to. **Add** covers anything you need to wire by hand.
{% endstep %}

{% step %}

#### Declare the shape: `Contract` tab

**Input contract** and **Output contract**, each viewable as **JSON** or **Schema**. Paste an example payload in the JSON view and the schema is generated live; the schema is the contract, and is hand-editable.
{% endstep %}

{% step %}

#### Read the logic back: `Diagram` tab

**Flow**, **Sequence** and **Docs** are all generated from the code and read-only: you edit the code and they follow. **Docs** carries an **End user** / **Technical** toggle and consumes AI credits when you **Regenerate**.
{% endstep %}

{% step %}

#### Confirm the scenarios: `Test cases` tab

The cases drafted during the build, grouped `happy-path`, `pagination`, `fields`, `edge-cases` and `error-handling`, each row an id such as `TC-01` with a `LIVE` or `MOCK` badge.
{% endstep %}

{% step %}

#### Watch it run: `Executions` tab

This workflow's own run history, filtered by the HTTP-status pills `All`, `200`, `201`, `400`, `404`, `422`, `500`. The neighbouring **Sync reports** tab fills in the first time the workflow runs `fastn.diff.compare`.
{% endstep %}

{% step %}

#### Hand it to callers: `API` and `Docs` tabs

**API** gives the `POST …/api/v1/workflows/<wfId>/execute` endpoint with a copyable curl and the two headers that steer it, `X-fastn-Test-Mode` and `x-fastn-env`. **Docs** is the runtime reference for what `ctx` and `fastn.*` expose inside the function.
{% endstep %}
{% endstepper %}

### The editor

Opening a workflow opens a drawer laid out as **configuration on the left, the tool tabs on the right, and (where code editing is enabled), the code editor between them**. That middle column is labelled `<slug>.js` and `JavaScript · export default async function(ctx)`. A workspace without code editing gets the same drawer minus that column.

Along the top: **Discard**, the workflow name, **Close tab**, **Save workflow** and **Publish**. Closing with unsaved edits asks first: *Discard unsaved changes?* / "This workflow has edits that have not been saved. Closing the tab throws them away." / **Keep editing** / **Discard changes**.

<figure><img src="https://1255842839-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3iSr2Tx8FvvuoLPncziH%2Fuploads%2Fgit-blob-307b27e1c7b3807ee8e41241f2831e91244896db%2Fworkflow-config-panel.jpg?alt=media" alt="The workflow Configuration panel scrolled to a Status toggle reading Enabled, a WHEN A RUN FAILS block with Retry policy and Escalate on timeout both off, and a PUBLISH &#x26; DEPLOY section"><figcaption><p>Deploy to environment sits under Publish snapshot, with the latest version noted beneath it.</p></figcaption></figure>

#### Configuration panel

**Identity**

| Field           | Notes                                                                        |
| --------------- | ---------------------------------------------------------------------------- |
| **Name**        | Required. Empty saves are refused with *Name is required.*                   |
| **Slug**        | Required when you create the workflow, and **cannot be changed afterwards**. |
| **Description** | What it does. The agent writes one; edit freely.                             |

**Execution**

| Field                 | Notes                                                                                                                                                                   |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Execution tier**    | `Instant` (default) (synchronous, result inline, max 30s. `Standard`), asynchronous via Temporal, returns 202, max 15 min. `Long`: asynchronous, returns 202, max 36 h. |
| **Execution timeout** | A slider constrained to the tier: 1s–30s, 5s–15min, or 30s–36h. Defaults are 30s, 2.0m and 15.0m respectively.                                                          |
| **Status**            | A toggle, on by default, and shown only on workflows that already exist. Off stops new runs without deleting anything.                                                  |

**WHEN A RUN FAILS**

The **Retry policy** toggle is off by default. Its own description sets the boundary: it retries transient failures, and code errors, data errors and out-of-memory never retry. Turning it on exposes four fields.

| Field                     | Range | Default |
| ------------------------- | ----- | ------- |
| **Max attempts**          | 1–10  | 3       |
| **Initial interval (ms)** | —     | 5000    |
| **Backoff coefficient**   | —     | 2       |
| **Max interval (ms)**     | —     | 60000   |

**Escalate on timeout** is a separate toggle, off by default and hidden on the Long tier. On timeout it retries one tier up (instant → standard) and an escalated instant run returns a queued execution id to poll rather than a synchronous result.

**PUBLISH & DEPLOY** (existing workflows only)

* **Publish snapshot**: freezes the current code and configuration as a version.
* **Deploy to environment**: sends a published version to an environment.
* Underneath: a row showing the environment's current status.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.fastn.ai/build/workflows/the-editor.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.