> For the complete documentation index, see [llms.txt](https://docs.hackle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hackle.io/en/development-guide/http-api/catalog.md).

# Catalog Management

Learn how to create and manage catalogs and items through the API.

A catalog is a **feature for storing data so you can reuse it**, such as products or content. Items placed in a catalog can be used for things like message personalization.

With the Catalog API, you can create catalogs, upload items, and update stored items.

To learn how to use catalog items in a message, see [Using Catalogs](https://docs.hackle.io/en/catalog/use.md).

### Authentication

Every request must pass the API key as a header.

| Header             | Value                                             |
| ------------------ | ------------------------------------------------- |
| `X-HACKLE-API-KEY` | API key (find it in Dashboard > Integration Info) |

### Basic Rules

* Base URL: `https://api.hackle.io`
* The request body uses `Content-Type: application/json`.
* Catalogs and fields are specified by **name**. Once created, a name cannot be changed.
* A catalog is created in **all environments** of the workspace, and items are stored only in **the environment of the API key**.

#### Field Types

<table><thead><tr><th width="126.140625">Type</th><th>Value format</th><th>Example</th></tr></thead><tbody><tr><td><code>STRING</code></td><td>String (750 characters or fewer)</td><td><code>"T-shirt"</code></td></tr><tr><td><code>NUMBER</code></td><td>Number (up to 20 integer digits and 10 decimal digits)</td><td><code>19900</code></td></tr><tr><td><code>BOOLEAN</code></td><td><code>true</code> / <code>false</code></td><td><code>true</code></td></tr><tr><td><code>TIME</code></td><td>ISO-8601 string or epoch seconds</td><td><code>"2026-08-01T00:00:00Z"</code>, <code>1754006400</code></td></tr></tbody></table>

***

### 1. List Catalogs

**Endpoint:** `GET https://api.hackle.io/v1/catalogs`

**Response Body**

| Field                   | Type   | Description                                               |
| ----------------------- | ------ | --------------------------------------------------------- |
| catalogs                | Array  | List of catalogs                                          |
| catalogs\[].catalogName | string | Catalog name                                              |
| catalogs\[].description | string | Catalog description                                       |
| catalogs\[].itemCount   | number | Number of items (based on the environment of the API key) |
| catalogs\[].createdAt   | string | Created at                                                |
| catalogs\[].modifiedAt  | string | Modified at                                               |

```json
{
  "catalogs": [
    {
      "catalogName": "products",
      "description": "Product catalog",
      "itemCount": 1024,
      "createdAt": "2026-08-01T10:00:00",
      "modifiedAt": "2026-08-01T10:00:00"
    }
  ]
}
```

**Response Codes**

* 200 OK: Success
* 401 Unauthorized: The header value is missing or the API key is invalid

***

### 2. Get a Catalog

**Endpoint:** `GET https://api.hackle.io/v1/catalogs/{catalogName}`

**Path Parameters**

| Field       | Type   | Required | Description  |
| ----------- | ------ | -------- | ------------ |
| catalogName | string | O        | Catalog name |

**Response Body**

| Field               | Type   | Description                                               |
| ------------------- | ------ | --------------------------------------------------------- |
| catalogName         | string | Catalog name                                              |
| description         | string | Catalog description                                       |
| itemCount           | number | Number of items (based on the environment of the API key) |
| createdAt           | string | Created at                                                |
| modifiedAt          | string | Modified at                                               |
| fields              | Array  | List of fields                                            |
| fields\[].fieldName | string | Field name                                                |
| fields\[].fieldType | string | Field type                                                |

```json
{
  "catalogName": "products",
  "description": "Product catalog",
  "itemCount": 1024,
  "createdAt": "2026-08-01T10:00:00",
  "modifiedAt": "2026-08-01T10:00:00",
  "fields": [
    { "fieldName": "name", "fieldType": "STRING" },
    { "fieldName": "price", "fieldType": "NUMBER" }
  ]
}
```

**Response Codes**

* 200 OK: Success
* 401 Unauthorized: The header value is missing or the API key is invalid
* 404 Not Found: No catalog with that name

***

### 3. Create a Catalog

**Endpoint:** `POST https://api.hackle.io/v1/catalogs`

**Request Body**

<table><thead><tr><th width="195.0859375">Field</th><th width="115.3671875">Type</th><th width="91.59375">Required</th><th>Description</th></tr></thead><tbody><tr><td>catalogName</td><td>string</td><td>O</td><td>Catalog name. Letters, numbers, <code>-</code>, and <code>_</code> only, 200 characters or fewer</td></tr><tr><td>description</td><td>string</td><td>X</td><td>Catalog description</td></tr><tr><td>fields</td><td>Array</td><td>X</td><td>List of fields to create together (up to 50)</td></tr><tr><td>fields[].fieldName</td><td>string</td><td>O</td><td>Field name. Must be unique within the catalog, and <code>id</code> cannot be used</td></tr><tr><td>fields[].fieldType</td><td>string</td><td>O</td><td><code>STRING</code> / <code>NUMBER</code> / <code>BOOLEAN</code> / <code>TIME</code></td></tr></tbody></table>

```json
{
  "catalogName": "products",
  "description": "Product catalog",
  "fields": [
    { "fieldName": "name", "fieldType": "STRING" },
    { "fieldName": "price", "fieldType": "NUMBER" }
  ]
}
```

**Response Body**

Same as Get a Catalog.

**Response Codes**

* 201 Created: Success
* 400 Bad Request: Invalid request
* 401 Unauthorized: The header value is missing or the API key is invalid
* 409 Conflict: A catalog with the same name already exists, or the catalog limit (20) has been exceeded

{% hint style="info" %}
If even one field fails to be created, the catalog is not created.
{% endhint %}

### 4. Delete a Catalog

**Endpoint:** `DELETE https://api.hackle.io/v1/catalogs/{catalogName}`

**Path Parameters**

| Field       | Type   | Required | Description  |
| ----------- | ------ | -------- | ------------ |
| catalogName | string | O        | Catalog name |

**Response Codes**

* 204 No Content: Success
* 401 Unauthorized: The header value is missing or the API key is invalid
* 404 Not Found: No catalog with that name

{% hint style="danger" %}
When you delete a catalog, the items it contained can no longer be used. The deleted name can be used again.
{% endhint %}

### 5. Add a Field

**Endpoint:** `POST https://api.hackle.io/v1/catalogs/{catalogName}/fields`

**Request Body**

<table><thead><tr><th width="116.0625">Field</th><th width="94.546875">Type</th><th width="98.60546875">Required</th><th>Description</th></tr></thead><tbody><tr><td>fieldName</td><td>string</td><td>O</td><td>Field name. Must be unique within the catalog, and <code>id</code> cannot be used</td></tr><tr><td>fieldType</td><td>string</td><td>O</td><td><code>STRING</code> / <code>NUMBER</code> / <code>BOOLEAN</code> / <code>TIME</code></td></tr></tbody></table>

```json
{ "fieldName": "brand", "fieldType": "STRING" }
```

**Response Body**

```json
{ "fieldName": "brand", "fieldType": "STRING" }
```

**Response Codes**

* 201 Created: Success
* 400 Bad Request: Invalid request
* 401 Unauthorized: The header value is missing or the API key is invalid
* 404 Not Found: No catalog with that name
* 409 Conflict: A field with the same name already exists, or the field limit (50) has been exceeded

***

### 6. Delete a Field

**Endpoint:** `DELETE https://api.hackle.io/v1/catalogs/{catalogName}/fields/{fieldName}`

**Path Parameters**

| Field       | Type   | Required | Description  |
| ----------- | ------ | -------- | ------------ |
| catalogName | string | O        | Catalog name |
| fieldName   | string | O        | Field name   |

**Response Codes**

* 204 No Content: Success
* 401 Unauthorized: The header value is missing or the API key is invalid
* 404 Not Found: No catalog or field with that name

***

### 7. Add Items

**Endpoint:** `POST https://api.hackle.io/v1/catalogs/{catalogName}/items`

**Request Body**

| Field           | Type   | Required | Description                                                                   |
| --------------- | ------ | -------- | ----------------------------------------------------------------------------- |
| items           | Array  | O        | List of items to add. At least 1 and at most 500                              |
| items\[].id     | string | O        | Item identifier. Letters, numbers, `-`, and `_` only, 300 characters or fewer |
| items\[].fields | Object | X        | Field names and values. Only fields defined in the catalog can be used        |

```json
{
  "items": [
    {
      "id": "P1",
      "fields": {
        "name": "T-shirt",
        "price": 19900
      }
    }
  ]
}
```

**Response Body**

| Field          | Type   | Description               |
| -------------- | ------ | ------------------------- |
| processedCount | number | Number of items processed |

```json
{ "processedCount": 1 }
```

**Response Codes**

* 200 OK: Success
* 400 Bad Request: Invalid request, or item validation failed (see Item Upload Failure)
* 401 Unauthorized: The header value is missing or the API key is invalid
* 404 Not Found: No catalog with that name
* 409 Conflict: Another upload is in progress for the same catalog

{% hint style="info" %}
An `id` that already exists is ignored. To change values, use Update Items.
{% endhint %}

### 8. Update Items

**Endpoint:** `PUT https://api.hackle.io/v1/catalogs/{catalogName}/items`

The request body and the response are the same as Add Items.

```json
{
  "items": [
    {
      "id": "P1",
      "fields": {
        "name": "T-shirt",
        "price": 15900
      }
    }
  ]
}
```

**The item is replaced in its entirety. Any field you do not send has its value cleared.** Even when you want to change only one field, you must send the remaining fields as well.

**Response Codes**

* 200 OK: Success
* 400 Bad Request: Invalid request, or item validation failed
* 401 Unauthorized: The header value is missing or the API key is invalid
* 404 Not Found: No catalog with that name
* 409 Conflict: Another upload is in progress for the same catalog

{% hint style="info" %}
An `id` that does not exist is ignored.
{% endhint %}

### 9. Delete Items

**Endpoint:** `DELETE https://api.hackle.io/v1/catalogs/{catalogName}/items`

**Request Body**

| Field | Type  | Required | Description                                                    |
| ----- | ----- | -------- | -------------------------------------------------------------- |
| ids   | Array | O        | List of item identifiers to delete. At least 1 and at most 500 |

```json
{ "ids": ["P1", "P2"] }
```

**Response Body**

```json
{ "processedCount": 2 }
```

**Response Codes**

* 200 OK: Success
* 400 Bad Request: Invalid request
* 401 Unauthorized: The header value is missing or the API key is invalid
* 404 Not Found: No catalog with that name
* 409 Conflict: Another upload is in progress for the same catalog

***

### Error Responses

Errors are returned in the following format.

```json
{
  "code": "CATALOG_NOT_FOUND",
  "message": "Could not find catalog with the given name"
}
```

| Status Code | code                          | Description                                                   |
| ----------- | ----------------------------- | ------------------------------------------------------------- |
| 400         | `bad_request`                 | The request body format is invalid                            |
| 400         | `CATALOG_NAME_INVALID`        | The catalog or field name violates the naming rules           |
| 400         | `CATALOG_FIELD_NAME_INVALID`  | The field name is duplicated or uses the reserved word (`id`) |
| 400         | `ITEM_UPLOAD_REQUEST_INVALID` | The number of items is outside the 1\~500 range               |
| 400         | `INVALID_PAGINATION`          | The page number or page size is out of range                  |
| 401         | -                             | The header value is missing or the API key is invalid         |
| 429         | `TOO_MANY_REQUESTS`           | The call limit has been exceeded                              |
| 404         | `CATALOG_NOT_FOUND`           | No catalog with that name                                     |
| 404         | `CATALOG_FIELD_NOT_FOUND`     | No field with that name                                       |
| 404         | `CATALOG_ITEM_NOT_FOUND`      | No item with that identifier                                  |
| 409         | `CATALOG_NAME_DUPLICATE`      | A catalog or field with the same name already exists          |
| 409         | `CATALOG_CAP_EXCEEDED`        | The catalog or field count limit has been exceeded            |
| 409         | `CONCURRENT_MODIFICATION`     | Another change is in progress for the same catalog            |
| 409         | `ITEM_UPLOAD_IN_PROGRESS`     | Another item upload is in progress for the same catalog       |
| 500         | `internal_server_error`       | Server error                                                  |

#### Item Upload Failure

If an item in an Add Items or Update Items request fails validation, a 400 is returned along with the position that failed. **If even one item fails, the entire request is not applied.**

```json
{
  "code": "TYPE_MISMATCH",
  "message": "Item value does not match the field type, or the field is not defined in the catalog",
  "failedRowNumber": 3,
  "failedValue": "price"
}
```

| Field           | Type   | Description                                   |
| --------------- | ------ | --------------------------------------------- |
| code            | string | Failure reason                                |
| message         | string | Description of the failure reason             |
| failedRowNumber | number | Position of the failed item (starting from 1) |
| failedValue     | string | The value that failed                         |

| code                 | Description                                                                             |
| -------------------- | --------------------------------------------------------------------------------------- |
| `TYPE_MISMATCH`      | The value does not match the field type, or a field not defined in the catalog was used |
| `LENGTH_EXCEEDED`    | The value is too long                                                                   |
| `ITEM_LIMIT_REACHED` | The catalog's item count limit has been exceeded                                        |
| `MISSING_ITEM_KEY`   | The item identifier is empty                                                            |
| `INVALID_ITEM_KEY`   | The item identifier violates the naming rules                                           |
| `MISSING_FIELD`      | A required value is missing                                                             |

***

### Rate Limits

Requests that change a catalog (creating or deleting catalogs and fields, and adding, updating, or deleting items) are limited to **50 calls per minute** per workspace and environment.

The number of remaining calls is returned in the response headers.

| Header                  | Description                                                |
| ----------------------- | ---------------------------------------------------------- |
| `X-RateLimit-Limit`     | The limit                                                  |
| `X-RateLimit-Remaining` | Number of remaining calls                                  |
| `X-RateLimit-Reset`     | Time at which the limit is restored (epoch seconds)        |
| `Retry-After`           | Seconds to wait before retrying when the limit is exceeded |

If you exceed the limit, a 429 is returned. Wait for the duration given in `Retry-After` and then retry.

```
{
  "code": "TOO_MANY_REQUESTS",
  "message": "Too many requests. Retry after the time in the Retry-After header"
}
```

***

### Limitations

| Item                    | Limit                                                |
| ----------------------- | ---------------------------------------------------- |
| Catalogs per workspace  | 20                                                   |
| Fields per catalog      | 50                                                   |
| Items per catalog       | 1,000,000 (per environment)                          |
| Items per request       | 1\~500                                               |
| Catalog and field names | Letters, numbers, `-`, `_` / 200 characters or fewer |
| Item identifier         | Letters, numbers, `-`, `_` / 300 characters or fewer |
| String value length     | 750 characters                                       |
| Number value            | 20 integer digits, 10 decimal digits                 |

* Catalog names and field names cannot be changed after they are created.
* `id` is reserved for the item identifier and cannot be used as a field name.
* To put a value in an item, you must create the field first. If you send a field that is not in the catalog, the request fails.
* The `processedCount` in the response is the number of items you requested. It also counts cases where you add an `id` that already exists or update or delete an `id` that does not exist.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hackle.io/en/development-guide/http-api/catalog.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
