> ## Documentation Index
> Fetch the complete documentation index at: https://netter.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Actions

> An Action is a named, governed write to an entity. Nothing writes to ontology data without one—apps and workflows all route through Actions, so every change is scoped, permissioned, and audited.

Direct edits to an entity are admin-only. An **Action** is how everything else writes: a named, admin-authored contract that says exactly what may be written to an entity, who may do it, and under what conditions. Apps and workflows don't write to entities on their own—they invoke an Action, and a write with no matching Action is refused.

Think of an Action as the safe, reusable verb for a change: "Mark ticket resolved," "Approve invoice," "Assign owner."

## What an Action defines

| Part              | What it controls                                                                                                                    |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Entity + kind** | Which entity it writes, and whether it can `create`, `modify`, or `delete` a row.                                                   |
| **Field writes**  | Which columns it may write—and how. A column can be a **fixed value** ("status → approved") or a **parameter** the caller supplies. |
| **Parameters**    | Typed inputs (text, number, date, boolean) with validation rules, for the parts of the write the caller fills in.                   |
| **Guards**        | Preconditions that must hold for the write to run—for example, only modify rows whose `status` is `pending`.                        |
| **Grants**        | Who may invoke it: by role (owner, admin, member) or specific members. Owners always can.                                           |

A write is allowed only when **all** of these line up: the right entity and kind, every written column covered by a field write, supplied values that pass their validation, every guard satisfied, and the caller named in the grants. Anything else is rejected.

### The three kinds

| Kind     | Effect                             |
| -------- | ---------------------------------- |
| `create` | Insert a new row.                  |
| `modify` | Update columns on an existing row. |
| `delete` | Remove a row.                      |

Each maps to a [row overlay](/docs/ontology/edit-rows) operation, so Actions never touch the source data the pipeline produced—a pipeline re-run won't clobber them.

## Multi-entity Actions

One Action can write more than one entity in a single invocation. It has an **anchor** entity plus **secondary** effects reached through to-one [relationships](/docs/ontology/overview)—for example, "close a ticket" can modify the `Ticket` and stamp a row on the related `Resolution`. The whole thing succeeds or is rejected together, and each affected entity fires its own change events for [workflows](/docs/assistant/overview) downstream.

## Strict enforcement

Every entity write routes through an Action—no exceptions and no fallback:

* **Apps** can only write through an Action. A [binding](/docs/applications/bindings) in `write` or `readwrite` mode is a prerequisite (it says the app may attempt that kind of write), but the named Action is the real authorization. A `read` binding can't write at all.
* **Workflows** resolve a named Action for each entity write they perform; a write node with no covering Action fails that item.
* There is **no default Action**, even for owners and admins—an ungoverned write is refused outright.

[Row-level security](/docs/permissions/row-level-security) still applies on top. An Action's grants decide *who* may invoke it; RLS decides *which rows* they can touch. A write the Action permits can still be blocked by RLS.

## Manage Actions

Admins and owners manage Actions from **Ontology → Actions**:

1. **New action** opens the editor: set the basics (name, description), define its **effects** (entity, kind, the columns it writes, and any guards), then set **grants** for who can run it.
2. Actions have a status—**draft**, **active**, or **archived**. Only active Actions authorize writes.
3. Edit or archive an Action from its row. Archiving stops it authorizing new writes without deleting its history.

Only company **admins and owners** can create, edit, or archive Actions. Members invoke the Actions they're granted, through apps or the entity's run panel.

## Create Action from chat

When you design an [app](/docs/applications/build) or a workflow that needs to write an entity, the [assistant](/docs/assistant/overview) checks whether a covering Action exists. If one doesn't, it surfaces a **Create Action** card pre-filled with the entity, kind, and the columns the write needs. You review it—add grants, guards, and parameters—and save. The new Action takes effect immediately; nothing needs re-wiring.

## Audit trail

Every invocation is logged: who ran it, when, from where (app, workflow, the ontology page, or chat), the columns written, and the result—including denials. Admins can review an entity's invocation history from its Actions view, so every change to ontology data is traceable to an Action and a person.

## Next

* [Edit rows](/docs/ontology/edit-rows) — the overlay mechanism Actions write through.
* [Application actions](/docs/applications/actions) — how a viewer triggers an Action from an app.
* [Row-level security](/docs/permissions/row-level-security) — the row filter applied on top of an Action's grants.