# Catalog Feeds

The Feeds API lets you upload, manage, and monitor product catalog feeds. Feeds are processed asynchronously — after you upload a feed file, it is validated, parsed, and transformed into standardized product offers.

**Base URL:** `https://api.violet.io`

## Authentication

All requests require a merchant API key passed as a Bearer token in the `Authorization` header.

```
Authorization: Bearer msk_{merchant_id}{uuid}
```

API keys follow the pattern `msk_` + your numeric merchant ID + a 32-character UUID. For example, if your merchant ID is `12345`:

```
Authorization: Bearer msk_12345abc11094a44800d84017c593e22
```

The service extracts your merchant ID from the key automatically. You do not need to pass it separately.

## Endpoints

| Method | Path                 | Description                                                             |
| ------ | -------------------- | ----------------------------------------------------------------------- |
| `POST` | `/v1/feeds`          | [Upload a product catalog feed](/feeds/feeds-overview/upload-feed.md)   |
| `GET`  | `/v1/feeds/{feedId}` | [Get details for a specific feed](/feeds/feeds-overview/get-feed.md)    |
| `GET`  | `/v1/feeds`          | [List all feeds for your merchant](/feeds/feeds-overview/list-feeds.md) |

## Feed Statuses

A feed progresses through these statuses during its lifecycle:

| Status       | Description                                                                    |
| ------------ | ------------------------------------------------------------------------------ |
| `PENDING`    | The feed has been uploaded and is waiting for processing to start.             |
| `PROCESSING` | The feed is currently being processed (parsed, validated, transformed).        |
| `ACTIVE`     | Processing completed successfully. Products are available.                     |
| `ERROR`      | Processing failed. Check the `errors` array on the feed details for specifics. |

## Error Response Format

All error responses follow the same structure:

```json
{
  "code": "ERROR_CODE",
  "message": "Human-readable description of what went wrong",
  "timestamp": "2024-03-15T10:30:00Z"
}
```

| Field       | Type              | Description                       |
| ----------- | ----------------- | --------------------------------- |
| `code`      | string            | Machine-readable error code.      |
| `message`   | string            | Human-readable error description. |
| `timestamp` | string (ISO 8601) | When the error occurred.          |

### HTTP Status Codes

| Status                      | Meaning                                              |
| --------------------------- | ---------------------------------------------------- |
| `200 OK`                    | Request succeeded.                                   |
| `202 Accepted`              | Request accepted; processing started asynchronously. |
| `400 Bad Request`           | Invalid parameters or validation failure.            |
| `401 Unauthorized`          | Invalid API credential.                              |
| `403 Forbidden`             | Attempting to access an unpermitted resource.        |
| `404 Not Found`             | Feed not found or not accessible for your merchant.  |
| `413 Payload Too Large`     | File exceeds the 2 GB size limit.                    |
| `500 Internal Server Error` | Unexpected server error.                             |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://merchant-help.violet.io/feeds/feeds-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.