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

# Manage colors

> Build and maintain the brand's reusable colour library — the colours items and styles reference as colourways.

<Info>
  **When to use this.** Colours are reusable library entities for a brand: you create them
  once, optionally organise them into colour groups, and then reference them as colourways on
  items and styles. Use these endpoints to build and maintain that library.
</Info>

## The workflow

A colour is a brand-level record in the colour library. The usual path is to (optionally) set
up colour groups for organisation, create the colours, then reference them from items and
styles further along the product lifecycle.

<Steps>
  <Step title="Group (optional)">
    `POST /api/color-groups` to create groups (e.g. "Blues", "Core") you'll file colours under.
  </Step>

  <Step title="Create colours">
    `POST /api/colors` with the colour details, attaching `colorGroupIds` to file them.
  </Step>

  <Step title="Find colours">
    `GET /api/colors` with filters (name, reference, state, group) to look colours up later.
  </Step>

  <Step title="Reference on products">
    Colours surface as colourways on items and style-items — see
    `GET /api/items/{itemId}/colors` and `GET /api/styles/{styleId}/items/{styleItemId}/colors`.
  </Step>
</Steps>

```mermaid theme={"dark"}
sequenceDiagram
  participant D as Designer
  participant API as Delogue API
  D->>API: POST /api/color-groups  (optional)
  API-->>D: group id
  D->>API: POST /api/colors  (with colorGroupIds)
  API-->>D: color id
  D->>API: GET /api/items/{itemId}/colors
  API-->>D: colours used on the item
```

## Walkthrough

Create a colour and file it under a colour group. The body is an array — one or many colours
are created in a single all-or-nothing transaction.

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST "https://service.my.delogue.com/api/colors" \
    -H "Accept: application/json" \
    -H "X-Auth-Token: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '[
    {
      "name": "Sky Blue",
      "userDefinedId": "SB-01",
      "userDefinedId2": null,
      "colorReference": "14-4318 TCX",
      "colorNote": "Spring palette",
      "state": "active",
      "colorGroupIds": [
        12
      ],
      "languageIds": [
        1
      ]
    }
  ]'
  ```

  ```js JavaScript theme={"dark"}
  const res = await fetch("https://service.my.delogue.com/api/colors", {
    method: "POST",
    headers: {
      "Accept": "application/json",
      "X-Auth-Token": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify([
    {
      "name": "Sky Blue",
      "userDefinedId": "SB-01",
      "userDefinedId2": null,
      "colorReference": "14-4318 TCX",
      "colorNote": "Spring palette",
      "state": "active",
      "colorGroupIds": [
        12
      ],
      "languageIds": [
        1
      ]
    }
  ]),
  });
  const { data } = await res.json();
  ```
</CodeGroup>

```json theme={"dark"}
{
  "status": "success",
  "code": "colors_created",
  "data": [
    {
      "id": 2579,
      "name": "Sky Blue",
      "userDefinedId": "SB-01",
      "userDefinedId2": null,
      "colorReference": "14-4318 TCX",
      "state": "active",
      "colorNote": "Spring palette",
      "colorGroups": [
        {
          "id": 12,
          "name": "Greens",
          "userDefinedId": "GRN",
          "state": "active"
        }
      ],
      "languageNames": [],
      "properties": []
    }
  ]
}
```

The response wraps the created colours in the standard envelope. Hold onto each `id` — items
and styles reference colours by it.

## Field reference

The fields that matter most when creating or updating a colour:

| Field            | What it means at Delogue                                                                                       |
| ---------------- | -------------------------------------------------------------------------------------------------------------- |
| `colorGroupIds`  | IDs of the color groups to associate with the new color.                                                       |
| `colorNote`      | Free-text note describing the color.                                                                           |
| `colorReference` | Color reference code, e.g. a Pantone code.                                                                     |
| `languageIds`    | IDs of the languages to link the color to. The translated text per language is managed by a separate endpoint. |
| `name`           | Display name of the color. Required.                                                                           |
| `state`          | Initial lifecycle state. Defaults to active.                                                                   |
| `userDefinedId`  | Customer-defined identifier (ID1).                                                                             |
| `userDefinedId2` | Secondary customer-defined identifier (ID2).                                                                   |

## Roles & permissions

Managing the colour library requires the **`colors`** permission on a **designer (brand)**
account — typically `CompanyAdmin` or `CompanyUser`. Supplier accounts collaborate on styles
but do not manage a brand's colour library.

## When things go wrong

Errors use the standard envelope (`status: "error"`, a `code`, and `error.details[]`). See
[Errors & responses](/concepts/errors) for the full list of codes and how to resolve them.

## What to call next

<CardGroup cols={2}>
  <Card title="Colour groups" href="/guides/color-groups">
    Organise colours into groups for filtering and reuse.
  </Card>

  <Card title="Item colours" href="/api-reference/items/get-color-cards-for-an-item">
    See which colours are used on an item: `GET /api/items/{itemId}/colors`.
  </Card>

  <Card title="Style-item colours" href="/api-reference/styleitems/get-colors-for-a-style-item">
    Colours on a style's items: `GET /api/styles/{styleId}/items/{styleItemId}/colors`.
  </Card>

  <Card title="Authentication" href="/authentication">
    How to get and send your `X-Auth-Token` API key.
  </Card>
</CardGroup>