# Register a feed source

`POST /catalog/v1/{catalog_id}/sources/feeds`

## Request example

```bash
curl --request POST \
  --url 'https://api.eu1.luigisbox.ai/catalog/v1/<catalog_id>/sources/feeds' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "active": true,
  "catalog_type": "example",
  "csv_delimiter": "example",
  "csv_has_header": true,
  "delete_threshold": 1,
  "format": "xml",
  "group_id_field": "example",
  "group_primary_attribute_name": "example",
  "group_primary_field": "example",
  "identity_field": "example",
  "item_tag": "example",
  "json_path": "example",
  "mapping_id": 1,
  "position": 0,
  "transport_options": {},
  "url": "example"
}'
```

## Path Parameters

| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `catalog_id` | `string` | Yes | Catalog Id | — |

## Request Body

**Required.**

### application/json

Schema: `object`

#### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `active` | `boolean` | No | Active | — |
| `catalog_type` | `string` | Yes | Catalog Type | >= 1 characters |
| `csv_delimiter` | `anyOf(string, null)` | No | Csv Delimiter | — |
| `csv_has_header` | `anyOf(boolean, null)` | No | Csv Has Header | — |
| `delete_threshold` | `anyOf(number, null)` | No | Delete Threshold | — |
| `format` | `anyOf(string, null)` | No | Format | — |
| `group_id_field` | `anyOf(string, null)` | No | Group Id Field | — |
| `group_primary_attribute_name` | `anyOf(string, null)` | No | Group Primary Attribute Name | — |
| `group_primary_field` | `anyOf(string, null)` | No | Group Primary Field | — |
| `identity_field` | `anyOf(string, null)` | No | Identity Field | — |
| `item_tag` | `anyOf(string, null)` | No | Item Tag | — |
| `json_path` | `anyOf(string, null)` | No | Json Path | — |
| `mapping_id` | `anyOf(integer, null)` | No | Mapping Id | — |
| `position` | `integer` | No | Position | >= 0 |
| `transport_options` | `anyOf(object, null)` | No | Transport overrides for fetching the feed (e.g. auth, headers). The object is open; the keys are not a fixed schema. | — |
| `transport_options.*` | `any` | No | Additional property. | — |
| `url` | `string` | Yes | Url | >= 1 characters |

#### Request body example

```json
{
  "active": true,
  "catalog_type": "example",
  "csv_delimiter": "example",
  "csv_has_header": true,
  "delete_threshold": 1,
  "format": "xml",
  "group_id_field": "example",
  "group_primary_attribute_name": "example",
  "group_primary_field": "example",
  "identity_field": "example",
  "item_tag": "example",
  "json_path": "example",
  "mapping_id": 1,
  "position": 0,
  "transport_options": {},
  "url": "example"
}
```

## Responses

| Status | Description | Content |
|---|---|---|
| `201` | Successful Response | application/json: object |
| `401` | Missing or invalid credentials | application/json: object |
| `403` | Authenticated but not permitted | application/json: object |
| `409` | State conflict | application/json: object |
| `422` | Request validation failed | application/json: object |

### 201

Successful Response

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `active` | `boolean` | Yes | Active | — |
| `catalog_id` | `string` | Yes | Catalog Id | — |
| `catalog_type` | `string` | Yes | Catalog Type | — |
| `created_at` | `string` | Yes | Created At | format: date-time |
| `csv_delimiter` | `anyOf(string, null)` | Yes | Csv Delimiter | — |
| `csv_has_header` | `anyOf(boolean, null)` | Yes | Csv Has Header | — |
| `delete_threshold` | `anyOf(number, null)` | Yes | Delete Threshold | — |
| `feed_id` | `integer` | Yes | Feed Id | — |
| `format` | `anyOf(string, null)` | Yes | Format | — |
| `group_id_field` | `anyOf(string, null)` | Yes | Group Id Field | — |
| `group_primary_attribute_name` | `anyOf(string, null)` | Yes | Group Primary Attribute Name | — |
| `group_primary_field` | `anyOf(string, null)` | Yes | Group Primary Field | — |
| `identity_field` | `anyOf(string, null)` | Yes | Identity Field | — |
| `item_tag` | `anyOf(string, null)` | Yes | Item Tag | — |
| `json_path` | `anyOf(string, null)` | Yes | Json Path | — |
| `mapping_id` | `anyOf(integer, null)` | Yes | Mapping Id | — |
| `position` | `integer` | Yes | Position | — |
| `transport_options` | `anyOf(object, null)` | Yes | Transport overrides for fetching the feed (e.g. auth, headers). The object is open; the keys are not a fixed schema. | — |
| `transport_options.*` | `any` | No | Additional property. | — |
| `updated_at` | `string` | Yes | Updated At | format: date-time |
| `url` | `string` | Yes | Url | — |
| `version` | `integer` | Yes | Version | — |

##### Response example

```json
{
  "active": true,
  "catalog_id": "example",
  "catalog_type": "example",
  "created_at": "2026-04-15T12:00:00Z",
  "csv_delimiter": "example",
  "csv_has_header": true,
  "delete_threshold": 1,
  "feed_id": 1,
  "format": "example",
  "group_id_field": "example",
  "group_primary_attribute_name": "example",
  "group_primary_field": "example",
  "identity_field": "example",
  "item_tag": "example",
  "json_path": "example",
  "mapping_id": 1,
  "position": 1,
  "transport_options": {},
  "updated_at": "2026-04-15T12:00:00Z",
  "url": "example",
  "version": 1
}
```

### 401

Missing or invalid credentials

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.validation_errors` | `anyOf(Array<object>, null)` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```

### 403

Authenticated but not permitted

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.validation_errors` | `anyOf(Array<object>, null)` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```

### 409

State conflict

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.validation_errors` | `anyOf(Array<object>, null)` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```

### 422

Request validation failed

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.validation_errors` | `anyOf(Array<object>, null)` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```