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

# Configuration reference

> Every field on an Agent, explained.

This page documents every field stored on an `Agent` and the resources it owns: rule sets, notification channels, data sources, and limits. The same field shapes are returned by `GET /api/v1/agents/{id}` and editable via `PATCH /api/v1/agents/{id}`.

## Identity

| Field         | Type    | Description                                                              |
| ------------- | ------- | ------------------------------------------------------------------------ |
| `name`        | string  | Human-readable label. Visible in the sidebar and notifications.          |
| `description` | string? | Optional longer note for teammates.                                      |
| `goal`        | string  | Plain-English goal that shapes the system prompt. Keep to 1-3 sentences. |
| `createdBy`   | string  | Clerk user ID of the creator. Read-only.                                 |

## Scope

`scope_json` declares what slice of the workspace the agent operates on. Out-of-scope tool calls return `error: "out_of_scope"` to the LLM.

| Field             | Type      | Description                                                  |
| ----------------- | --------- | ------------------------------------------------------------ |
| `scope.suppliers` | string\[] | Supplier codes (e.g. `["BOOKING", "EXPEDIA"]`). Empty = all. |
| `scope.regions`   | string\[] | ISO country/region codes. Empty = all.                       |
| `scope.sources`   | string\[] | Inventory source identifiers. Empty = all.                   |

## Schedule & status

| Field          | Type    | Description                                                                                                                                                                                                                      |
| -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scheduleCron` | string? | Cron expression (UTC). Null = event-triggered only.                                                                                                                                                                              |
| `status`       | enum    | `DRAFT`, `ACTIVE`, `PAUSED_USER`, `PAUSED_COST`, `PAUSED_RATE`, `ARCHIVED`. A newly created agent (`POST /api/v1/agents`) starts in **`DRAFT`** — it does not run until you activate it via `POST /api/v1/agents/{id}/activate`. |

## LLM provider

| Field            | Type    | Description                                                                                             |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `llmProvider`    | enum    | `HOSTED_ANTHROPIC` (default), `BYO_ANTHROPIC`, `BYO_OPENAI`.                                            |
| `llmModel`       | string  | `claude-opus-4-7` (default), `claude-haiku-4-5-20251001`, `gpt-4.1`, etc.                               |
| `byoKeySecretId` | string? | Vault reference to your API key (BYO only). See [BYO Anthropic key](/agents/recipes/byo-anthropic-key). |

## Cost & rate limits

| Field                | Type | Description                                                       |
| -------------------- | ---- | ----------------------------------------------------------------- |
| `dailySpendCapCents` | int  | Soft pause when the daily ledger exceeds this. Default 500 (\$5). |
| `hourlyActionCap`    | int  | Hard pause when actions in the last hour exceed this. Default 60. |

See [Cost and limits](/agents/cost-and-limits) for cap semantics.

## Rule set

Rule sets are **versioned** — every save creates a new row, and every run records the version it executed under. Edit via `POST /api/v1/agents/{id}/rule-sets`. See [Rules and decisions](/agents/rules-and-decisions) for the full schema.

| Group                                      | Purpose                                                           |
| ------------------------------------------ | ----------------------------------------------------------------- |
| `mapping_jobs`                             | When to trigger jobs (upload, cron, golden-dataset change).       |
| `unmatched_results`                        | How to handle unmatched rows (max candidates, search strategies). |
| `mismatch_reports`                         | Triage policy.                                                    |
| `coverage`                                 | Alert thresholds + digest cadence.                                |
| `data_sources`                             | Auto-pull cadence + failure-pause threshold.                      |
| `data_sinks`                               | Auto-push policy (default off).                                   |
| `mode_preference`, `export`, `bulk_update` | Off by default; explicit opt-in.                                  |
| `notifications`                            | Cost-threshold percentage + event subscriptions.                  |

## Notification channels

Resource `agent_notification_channel`. See [Notifications](/agents/notifications).

| Field                | Type      | Description                                                              |
| -------------------- | --------- | ------------------------------------------------------------------------ |
| `type`               | enum      | `EMAIL`, `SLACK_WEBHOOK`, `GENERIC_WEBHOOK`.                             |
| `target`             | string    | Email address, Slack incoming-webhook URL, or HTTPS URL.                 |
| `eventSubscriptions` | string\[] | Subset of `on_action`, `on_escalation`, `on_pause`, `on_cost_threshold`. |
| `enabled`            | boolean   | Toggle without deleting.                                                 |

## Data sources & sinks

Resource `agent_data_source`. See [Data sources and sinks](/agents/data-sources-and-sinks).

| Field          | Type    | Description                                                               |
| -------------- | ------- | ------------------------------------------------------------------------- |
| `role`         | enum    | `INVENTORY_SOURCE` (inbound) or `RESULTS_SINK` (outbound).                |
| `type`         | enum    | `S3` or `HTTPS_WEBHOOK`.                                                  |
| `name`         | string  | Display label.                                                            |
| `configJson`   | object  | Type-specific (bucket/prefix/region for S3; URL/auth scheme for webhook). |
| `secretRef`    | string? | Vault id for credentials. Never returned in full.                         |
| `format`       | enum    | `CSV`, `JSON`, `XLSX`.                                                    |
| `scheduleCron` | string? | Per-source schedule (overrides the agent's).                              |
| `enabled`      | boolean | Toggle without deleting.                                                  |

## Read-only fields

| Field                                                      | Description                  |
| ---------------------------------------------------------- | ---------------------------- |
| `id`, `workspaceId`, `createdAt`, `updatedAt`, `deletedAt` | Standard.                    |
| `lastSyncedAt`, `lastStatus`, `lastError` (data sources)   | Updated by the sync runtime. |

## Related

* [Agents overview](/agents/overview) — context for what these fields shape.
* [Rules and decisions](/agents/rules-and-decisions) — the rule-set JSON in detail.