# Technical reference

> Reference documentation for Conclude’s app model — the YAML definition that shapes a channel’s activities, automations, integrations, and AI agents.

Canonical HTML page: https://conclude.io/doc/reference/
Last updated: 2026-11-02

---

Reference documentation for Conclude's app model — the YAML definition that
shapes a channel's activities, automations, integrations, and AI agents.

## Contents

| Doc | Covers |
|---|---|
| [App YAML](https://conclude.io/doc/reference/yaml/) | Top-level YAML structure, every field on the `App` type |
| [Attributes](https://conclude.io/doc/reference/attributes/) | Attribute types, options, visibility, ACLs |
| [Statuses and states](https://conclude.io/doc/reference/statuses/) | Activity states, built-in/custom statuses, Zendesk + Jira mapping |
| [Triggers](https://conclude.io/doc/reference/triggers/) | `onCreate` / `onComment` / `onEdit` / `onConclude`, conditions, actions |
| [Scripting (Starlark)](https://conclude.io/doc/reference/scripting/) | Starlark API, scheduled re-entry, `conclude.editComment` / `conclude.schedule` |
| [Agents in YAML](https://conclude.io/doc/reference/agents/) | AI agent configuration and trigger wiring |
| [Connectors](https://conclude.io/doc/reference/connectors/) | Email, web, Jira, Zendesk, lookup endpoints |
| [Macros and roles](https://conclude.io/doc/reference/macros-and-roles/) | Role expressions, install-time and runtime macros |

## What an app is

An **app** is a YAML document that turns a channel into a structured workspace
for a specific kind of work — support tickets, incidents, approvals,
decisions. Installing an app on a channel binds the channel to that
definition; everything the channel does after that — activity creation,
attribute prompts, automations, AI agents, integrations — is shaped by the
YAML.

The smallest valid app declares a `name`, a `label`, and at least one
attribute (which must include `title`):

```yaml
name: simple
label: Simple
attributes:
  - name: title
    type: string
    label: Subject
    mandatory: true
```

## Conceptual model

```
   Channel ── installs ──> App (YAML)
                            │
                            ├── Settings        — operational config
                            ├── Roles           — who can do what
                            ├── Texts           — UI text overrides
                            │
                            ├── Attributes[]    — fields on each activity
                            │       └── Options, Triggers
                            │
                            ├── Triggers[]      — onCreate/onComment/onEdit/onConclude
                            │       └── Actions: setAttribute, message, email,
                            │           conclude, agent, script
                            │
                            ├── Scripts[]       — named Starlark
                            ├── agent actions   — organization agents named in triggers
                            │
                            ├── EmailConnector  — inbound email
                            ├── WebConnector    — inbound web form
                            ├── Jira / Zendesk  — external sync
                            └── Lookup          — HTTP enrichment endpoint
```

An **activity** is one instance of work tracked under the app — one ticket,
one incident, one approval request. Each activity has the attributes the app
declares. Triggers fire as the activity moves through its lifecycle.

## Lifecycle

```
[user posts in channel]
        │
        ▼
   onCreate ──► attributes filled / triggers fire / agents engaged
        │
        ▼
   activity open
        │
        ├── onComment   (user replies)
        ├── onEdit      (attribute changed)
        └── onConclude  (activity closed)
```

Scripts and
agents only fire on user-originated events (loop protection via the call
stack — see [Scripting (Starlark)](https://conclude.io/doc/reference/scripting/#loop-protection)).

## Where to start reading

- **New to Conclude apps:** read this page, then look at the
  [bundled apps](#bundled-apps-canonical-examples) — `support.yaml`, `incident.yaml`, `approval.yaml`
  are good starting points.
- **Writing your first app:** [App YAML](https://conclude.io/doc/reference/yaml/) and
  [Attributes](https://conclude.io/doc/reference/attributes/).
- **Adding automation:** [Triggers](https://conclude.io/doc/reference/triggers/), then
  [Scripting (Starlark)](https://conclude.io/doc/reference/scripting/) or [Agents in YAML](https://conclude.io/doc/reference/agents/) depending on
  whether you want deterministic logic or AI behavior.
- **Connecting to external systems:** [Connectors](https://conclude.io/doc/reference/connectors/).

## Bundled apps (canonical examples)

| File | Demonstrates |
|---|---|
| `support.yaml` | Minimal support ticket |
| `incident.yaml` | Status states, severity, postmortem |
| `approval.yaml` | Superusers role, option-driven close |
| `contact-form.yaml` | Web connector, attribute mapping |
| `bug.yaml` | Status + severity, conclusion templates |
| `jira.yaml` | Jira integration, display macros |

## Pages in this section

- [App YAML](https://conclude.io/doc/reference/yaml/index.html.md): Top-level structure of an app YAML.
- [Attributes](https://conclude.io/doc/reference/attributes/index.html.md): Attributes are the fields on each activity — the title, the body, the category, the deadline. The attributes: list shapes the activity form and the activity itself.
- [Statuses and states](https://conclude.io/doc/reference/statuses/index.html.md): Every activity has two related notions of “where it is in its lifecycle”:
- [Triggers](https://conclude.io/doc/reference/triggers/index.html.md): Triggers are reactions to events on an activity. Each trigger has an event (when it fires), optional conditions (whether it fires), and one or more actions (what it does).
- [Scripting (Starlark)](https://conclude.io/doc/reference/scripting/index.html.md): Scripts are inline Starlark code that runs in response to triggers. They can read/write attributes, post and edit comments, and schedule themselves to fire again later.
- [Agents in YAML](https://conclude.io/doc/reference/agents/index.html.md): Agents are LLM-backed participants in a channel’s activities. They read the ticket context and conversation history, then respond with a comment.
- [Connectors](https://conclude.io/doc/reference/connectors/index.html.md): Connectors bring data into a Conclude app from outside the chat platform — email, web forms, ticketing systems — or push enrichment data into an agent’s context.
- [Macros and roles](https://conclude.io/doc/reference/macros-and-roles/index.html.md): Roles control who can do things; macros let YAML reference who and what dynamically. They share a syntax — a role is essentially a macro that resolves to one or more users or channels.
- [HTTP endpoints](https://conclude.io/doc/reference/endpoints/index.html.md): The public HTTP endpoints Conclude exposes for web forms and inbound email, with request and response shapes from the code.
- [Example apps](https://conclude.io/doc/reference/examples/index.html.md): Annotated walkthroughs of the bundled support, incident, approval and contact-form app definitions, block by block, for builders reading YAML.