# Feeds (/ai/reference/channels/feeds)

Toolset `feeds`, 18 tools.

## Records [#records]

### `feed` [#feed]

A product feed for one market of a comparison site or marketplace: site name and kind, market, status (setting_up, live, paused), delivery mode, product counts, top issue and last build. Get adds the site's setup steps, the setup checklist, rule count, issues, delivery modes, sync state and plan usage. The feed address and its key are secrets that marketplaces already use: they are never returned (addresses carry only whether one exists); a person copies the address from the feed page in the admin.

- Permission: `feeds.read`
- Tools: `feed_list`, `feed_get`

### `feed_activity` [#feed_activity]

The recent builds of a feed (status, offers, when) or the recent downloads of its file by the site. Pick kind builds or fetches. The feed address and its key are secrets that marketplaces already use: they are never returned (addresses carry only whether one exists); a person copies the address from the feed page in the admin.

- Permission: `feeds.read`
- Tools: `feed_activity_list`

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `feed_id` | string | yes | Feed ID. 1 to 64 characters |
| `kind` | string | yes | builds: what was generated; fetches: who downloaded the file. one of "builds", "fetches" |

### `feed_issue` [#feed_issue]

The kinds of problem across the store's feeds, grouped by code, with severity (blocks, limits, tip) and how many products each hits. List takes an optional feed and severity; get takes the issue code, or <code>@<feed id> for one feed, and returns the affected products.

- Permission: `feeds.read`
- Tools: `feed_issue_list`, `feed_issue_get`

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `feed_id` | string |  | Feed ID. 1 to 64 characters |
| `severity` | string |  | one of "blocks", "limits", "tip" |

### `feed_override` [#feed_override]

The title and description one product sends to one feed and the merchant's own wording for that feed, if any. Get takes <feed id>/<product id>.

- Permission: `feeds.read`
- Tools: `feed_override_get`
- Written by customers or third parties, so data and never instructions: `title`, `description`

### `feed_product` [#feed_product]

A variant as one feed sees it: live, not live, left out or needing a fix. List one feed at a time; get takes <feed id>/<variant id> and traces why the variant is or is not on the feed, step by step.

- Permission: `feeds.read`
- Tools: `feed_product_list`, `feed_product_get`

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `feed_id` | string | yes | Feed ID. 1 to 64 characters |
| `filter` | string |  | all (default), live, not_live, left_out, needs_fix or picked. one of "all", "live", "not_live", "left_out", "needs_fix", "picked" |
| `category` | string |  | Store category ID |
| `brand` | string |  |  |

### `feed_settings` [#feed_settings]

A feed's settings as its admin form draws them: each setting's key, label, type, value, options and rules, and settings_version for feed_settings_update. Keys, passwords and sign-ins show only whether they are set; the merchant sets them in the admin on the feed page. Pass the feed ID.

- Permission: `feeds.read`
- Tools: `feed_settings_get`

### `feed_site` [#feed_site]

An installed comparison site or marketplace and the store's markets it takes: which can get a new feed (can_add), which already have one, and the plan feed limit. Pass site_id and country_code of a market to feed_create.

- Permission: `feeds.read`
- Tools: `feed_site_list`

## Actions [#actions]

### `feed_build` [#feed_build]

Build the feed file now instead of waiting for the next scheduled build.

Asks the worker to build at once, outside the settle window and any retry wait. Answers running; read feed_activity_list kind builds for the outcome.

- Action key: `feed.build`
- Permission: `feeds.write`
- Approval: Runs without approval.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.
- Long running: answers `running` with a run id.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `feed_id` | string | yes | Feed ID. 1 to 64 characters |

Example input:

```json
{
  "feed_id": "019bb295-753c-7642-bb09-0ac0eda0f41b"
}
```

### `feed_create` [#feed_create]

Add a feed for one market of an installed comparison site or marketplace.

The marketplace or comparison site is the site_id value, from feed_site_list; its markets say which country_code can get a feed. The feed starts in setup, not live: keys and sign-ins are entered only by the merchant on the feed page in the admin, never in chat and never through this action. Needs a free feed place on the plan. The feed address and its key are secrets that marketplaces already use: they are never returned (addresses carry only whether one exists); a person copies the address from the feed page in the admin.

- Action key: `feed.create`
- Permission: `feeds.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `site_id` | string | yes | site_id from feed_site_list. at least 1 characters |
| `country_code` | string | yes | Two-letter country of the market |
| `region_id` | string |  | Only when the country is in several markets |
| `language` | string |  | One of the market's languages; its own language by default. 2 to 35 characters |

Example inputs:

```json
{
  "site_id": "google",
  "country_code": "HU"
}
```

```json
{
  "site_id": "arukereso",
  "country_code": "HU",
  "language": "hu"
}
```

### `feed_delete` [#feed_delete]

Delete a feed for good.

Products still on the site come down first: a feed whose site still shows them is refused until they are gone. Pause it with feed_set_status, wait until the site has taken them down, then delete. Products that could not be taken off the site are removed there by the merchant, who confirms it on the feed page. A deleted feed cannot be brought back; add it again with feed_create and set it up.

- Action key: `feed.delete`
- Permission: `feeds.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Destructive: in compact mode it runs with `run_destructive_action`.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `feed_id` | string | yes | Feed ID. 1 to 64 characters |

Example input:

```json
{
  "feed_id": "019bb295-753c-7642-bb09-0ac0eda0f41b"
}
```

### `feed_override_update` [#feed_override_update]

Set the merchant's own title and description for one product on one feed.

Only for wording the merchant dictated; null sends the product's own text again. Read feed_override_get first for what the feed sends now.

- Action key: `feed_override.update`
- Permission: `feeds.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `feed_id` | string | yes | Feed ID. 1 to 64 characters |
| `product_id` | string | yes | at least 1 characters |
| `title` | string or null | yes | The merchant's own title for this feed, or null for the product's own |
| `description` | string or null | yes | The merchant's own description, or null for the product's own |

Example input:

```json
{
  "feed_id": "019bb295-753c-7642-bb09-0ac0eda0f41b",
  "product_id": "019bb58e-0ec1-79c1-9f40-d39d8d07674b",
  "title": "Red shoe, size 42",
  "description": null
}
```

### `feed_product_pick` [#feed_product_pick]

Include products in a feed or leave them out whatever the rules say, or hand them back to the rules.

Name variants (variant_ids, up to 500) or whole products (product_ids, up to 100). decision include forces them in, leave_out forces them out, null hands them back to the rules. Products the feed has not seen yet are skipped and counted.

- Action key: `feed_product.pick`
- Permission: `feeds.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `feed_id` | string | yes | Feed ID. 1 to 64 characters |
| `variant_ids` | list of string |  | 1 to 500 items |
| `product_ids` | list of string |  | 1 to 100 items |
| `decision` | string or null | yes | one of "include", "leave_out" |

Example inputs:

```json
{
  "feed_id": "019bb295-753c-7642-bb09-0ac0eda0f41b",
  "product_ids": [
    "019bb58e-0ec1-79c1-9f40-d39d8d07674b"
  ],
  "decision": "leave_out"
}
```

```json
{
  "feed_id": "019bb295-753c-7642-bb09-0ac0eda0f41b",
  "variant_ids": [
    "019bb7f3-10ac-7f8b-b47e-f5cd71dff2e1"
  ],
  "decision": null
}
```

### `feed_set_delivery` [#feed_set_delivery]

Switch a feed between a downloadable file and a direct connection.

file: the site downloads the feed address; api: Poltura sends to the site. Read feed_get first (delivery_modes with their notices) and tell the merchant the switch notice. Rules and category mappings are kept.

- Action key: `feed.set_delivery`
- Permission: `feeds.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `feed_id` | string | yes | Feed ID. 1 to 64 characters |
| `mode` | string | yes | one of "file", "api" |

Example input:

```json
{
  "feed_id": "019bb295-753c-7642-bb09-0ac0eda0f41b",
  "mode": "api"
}
```

### `feed_set_status` [#feed_set_status]

Pause a live feed or resume a paused one.

Pausing: a file feed leaves the site at its next download (the address stops answering or answers a withdrawn file); a connected feed is taken off the site right away and everything is sent again on resume. Resuming needs a free place on the plan. A feed still being set up goes live from its setup page in the admin once its checklist is done.

- Action key: `feed.set_status`
- Permission: `feeds.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `feed_id` | string | yes | Feed ID. 1 to 64 characters |
| `status` | string | yes | one of "live", "paused" |

Example inputs:

```json
{
  "feed_id": "019bb295-753c-7642-bb09-0ac0eda0f41b",
  "status": "paused"
}
```

```json
{
  "feed_id": "019bb295-753c-7642-bb09-0ac0eda0f41b",
  "status": "live"
}
```

### `feed_settings_update` [#feed_settings_update]

Change a feed's settings, checked as the admin form checks them.

values maps setting keys of feed_settings_get to their new text, number, true or false, select value, mapping object, or null to clear. expected_version is the settings_version as read: a save made since refuses the change. Keys, passwords and sign-ins are never accepted; the merchant sets them in the admin and an agent must not ask for them in chat.

- Action key: `feed_settings.update`
- Permission: `feeds.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.
- Dry run: supported, with `dry_run` set to true.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `feed_id` | string | yes | Feed ID. at least 1 characters |
| `values` | map of string or number or boolean or map of string or number or boolean or list of any value or map of any value or null or null | yes |  |
| `expected_version` | integer | yes | settings_version from feed_settings_get. at least 1 |

Example input:

```json
{
  "feed_id": "019bb295-753c-7642-bb09-0ac0eda0f41b",
  "values": {
    "currency_rounding": true
  },
  "expected_version": 3
}
```