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

# Overview

> Read, manage, version, and generate rules through Fini's public API.

The Rules API manages two resources with different lifecycles: versioned intent rules and unversioned Business Rules. Every endpoint in this section uses a workspace API key.

<Info>
  The API paths use `/hc-rules`, which is the current controller contract. This reference calls these resources **rules** to match the product.
</Info>

<CardGroup cols={2}>
  <Card title="Intent rules" icon="route" href="/en/api-reference/intent-rules">
    Rulebook workflows with drafts, published versions, version history, generation, and restore.
  </Card>

  <Card title="Business rules" icon="briefcase" href="/en/api-reference/business-rules">
    Widget-escalation workflows with custom and Fini-provided template modes.
  </Card>

  <Card title="Evaluate rule" icon="play" href="/en/api-reference/evaluate-rule">
    Run a saved rule against supplied input context and inspect node results.
  </Card>

  <Card title="Generate Rulebook tests" icon="vial" href="/en/api-reference/generate-rulebook-tests">
    Generate suggested test cases from a Rulebook flow.
  </Card>
</CardGroup>

## Endpoint relevance

| Endpoint family                                   | Intent rules  | Business Rules |
| ------------------------------------------------- | ------------- | -------------- |
| List, get, fields context, create, update, delete | Supported     | Supported      |
| Duplicate and direct evaluation                   | Supported     | Supported      |
| Test-field preview and extraction                 | Supported     | Supported      |
| Generate draft content with an LLM                | Supported     | Not supported  |
| Generate Rulebook tests                           | Supported     | Not supported  |
| Version history, publish draft, restore as draft  | Supported     | Not supported  |
| Default templates                                 | Not supported | Supported      |

<Note>
  The six endpoints that support both rule types share paths. Use `type=intent` or `type=business` on list and fields-context requests, and send the `type` explicitly when creating a rule.
</Note>

## Rule summary object

List and default-template routes return rule summaries without `flowConfig`.

### Fields shared by both rule types

<ResponseField name="id" type="string">
  Rule ID.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 last-update timestamp.
</ResponseField>

<ResponseField name="companyId" type="string | null">
  Workspace ID. Fini-provided default templates use `null`.
</ResponseField>

<ResponseField name="name" type="string">
  Rule name.
</ResponseField>

<ResponseField name="description" type="string">
  Natural-language rule description.
</ResponseField>

### Intent-rule lifecycle fields

<ResponseField name="isDraft" type="boolean">
  Whether the resolved intent-rule version is a draft.
</ResponseField>

<ResponseField name="version" type="number">
  Resolved version number for an intent rule.
</ResponseField>

<ResponseField name="versionId" type="string">
  Resolved version ID for an intent rule.
</ResponseField>

<ResponseField name="status" type="string">
  Version status. Current values are `DRAFT`, `PUBLISHED`, and `ARCHIVED`.
</ResponseField>

<ResponseField name="parentVersionId" type="string | null">
  Published version from which a draft was created.
</ResponseField>

<ResponseField name="publishedAt" type="string | null">
  ISO 8601 publication timestamp.
</ResponseField>

<ResponseField name="isStale" type="boolean">
  Whether a draft is based on an older published version.
</ResponseField>

<ResponseField name="currentPublishedVersionId" type="string | null">
  Current published version ID.
</ResponseField>

### Assignment and type fields

<ResponseField name="botIds" type="string[]">
  Assigned agent IDs when the selected list mode includes assignments.
</ResponseField>

<ResponseField name="type" type="string">
  `intent` or `business`.
</ResponseField>

### Business Rule configuration fields

<ResponseField name="defaultRuleId" type="string | null">
  Fini-provided template used by this rule, if any.
</ResponseField>

<ResponseField name="source" type="string | null">
  Rule source. The current enum value is `widget`.
</ResponseField>

<ResponseField name="triggerType" type="string | null">
  Business-rule trigger. The current enum value is `on_escalation`.
</ResponseField>

<ResponseField name="inputSchema" type="InputSchemaField[]">
  Optional runtime input schema.
</ResponseField>

## Rule object

The full rule object includes every applicable rule-summary field plus these fields:

<ResponseField name="flowConfig" type="RuleNodeConfig">
  Full rule tree.
</ResponseField>

<ResponseField name="botIds" type="string[]">
  Agent IDs assigned to the rule. Draft responses return an empty array.
</ResponseField>

## Rule version object

Rule version objects apply only to intent rules.

<ResponseField name="id" type="string">
  Version ID.
</ResponseField>

<ResponseField name="ruleId" type="string">
  Parent rule ID.
</ResponseField>

<ResponseField name="versionNumber" type="number">
  Monotonically increasing version number.
</ResponseField>

<ResponseField name="status" type="string">
  `DRAFT`, `PUBLISHED`, or `ARCHIVED`.
</ResponseField>

<ResponseField name="name" type="string">
  Name captured in this version.
</ResponseField>

<ResponseField name="description" type="string">
  Description captured in this version.
</ResponseField>

<ResponseField name="parentVersionId" type="string | null">
  Published version on which this version is based.
</ResponseField>

<ResponseField name="publishedAt" type="string | null">
  ISO 8601 publication timestamp.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 last-update timestamp.
</ResponseField>

<ResponseField name="isCurrentPublished" type="boolean">
  Whether this is the rule's active published version.
</ResponseField>

<ResponseField name="isStale" type="boolean">
  Whether this draft is based on an older published version.
</ResponseField>

<ResponseField name="flowConfig" type="RuleNodeConfig | null">
  Full version tree. Present on the get-version route and omitted from version-list items.
</ResponseField>

## RuleNodeConfig object

<ResponseField name="root" type="string">
  Root node ID.
</ResponseField>

<ResponseField name="nodes" type="object">
  Map of node IDs to node configs. Every node has `id`, `name`, and `type`, plus fields specific to that node type.
</ResponseField>

Current node types are `SEQUENCE`, `SELECTOR`, `CONDITION`, `ACTION`, and `WIDGET_FORM_RENDERER`. Current action subtypes are `LLM_EXTRACTION`, `TOOL_CALL`, `PROMPT_INJECTION`, `WIDGET_FORM_VALIDATION_ERROR`, and `SEND_MESSAGE`.

## InputSchemaField object

<ResponseField name="name" type="string">
  Field name.
</ResponseField>

<ResponseField name="dataType" type="string">
  `string`, `number`, `boolean`, `array`, `object`, or `date`.
</ResponseField>

<ResponseField name="required" type="boolean">
  Whether the field is required.
</ResponseField>

<ResponseField name="path" type="string">
  Optional runtime path to bind from.
</ResponseField>

<ResponseField name="value" type="any">
  Optional literal value.
</ResponseField>

<ResponseField name="source" type="string">
  Optional source: `metadata`, `jwt`, or `apiResponse`.
</ResponseField>

<ResponseField name="defaultValue" type="any">
  Optional fallback value.
</ResponseField>

<ResponseField name="autoBindPath" type="string">
  Optional context path to bind automatically.
</ResponseField>

<Warning>
  Rule creation and update validate referenced agent IDs, actions, and widget forms. Template-based rules cannot define their own `flowConfig`.
</Warning>