> ## 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 style files

> Attach, organise and update the files on a style — tech packs, artwork and reference documents, filed into the style's folders.

<Info>
  **When to use this.** Style files are the documents attached to a single style — tech packs,
  artwork, and reference files — filed into that style's folders. Use these endpoints to attach
  an already-uploaded file to a style, organise and rename it, link it to a colourway, and read
  the files back either folder-by-folder or as a flat, filterable list.
</Info>

## The workflow

A style file wraps a file resource (the uploaded bytes) and places it in one of the style's
folders. The usual path is to upload the resource, attach it to the style, keep it tidy with
bulk updates, then read the files back.

<Steps>
  <Step title="Upload the resource">
    Upload the file bytes via the file upload endpoint to get a `fileResourceId` (a GUID). A
    style file must reference a resource that already exists — a create with an empty resource is
    rejected.
  </Step>

  <Step title="Attach to a style">
    `POST /api/styles/{styleId}/files` with the `fileResourceId` and the `folderId` of the
    folder to file it under. The body is an array, so you can attach several files in one
    all-or-nothing transaction. Names must be unique among active files in the same folder.
  </Step>

  <Step title="Organise & update">
    `PUT /api/styles/{styleId}/files` (or the cross-style `PUT /api/style-files`) to rename,
    re-position, link a colourway, or deactivate files. These are bulk updates: send the `id`
    plus only the fields you want to change — a `null` field is left unchanged.
  </Step>

  <Step title="Retrieve">
    `GET /api/styles/{styleId}/files` returns the style's folders with their files embedded;
    `GET /api/style-files` returns a flat, filterable, paginated list across the organization.
  </Step>
</Steps>

```mermaid theme={"dark"}
sequenceDiagram
  participant D as Designer
  participant API as Delogue API
  D->>API: (upload file resource) -> fileResourceId
  D->>API: POST /api/styles/{styleId}/files  (fileResourceId + folderId)
  API-->>D: style file id
  D->>API: PUT /api/styles/{styleId}/files  (rename / reposition / deactivate)
  D->>API: GET /api/styles/{styleId}/files
  API-->>D: folders with files embedded
```

## Walkthrough

Attach two files to a style's folder, then bulk-update them. The request body is an array — one
or many files are created (or updated) in a single all-or-nothing transaction.

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST "https://service.my.delogue.com/api/styles/{styleId}/files" \
    -H "Accept: application/json" \
    -H "X-Auth-Token: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '[
    {
      "fileResourceId": "3f8a9c2e-1b4d-4e77-9a01-6c2d5e8b1f30",
      "folderId": 610,
      "name": "tech-pack.pdf",
      "note": "Rev B — updated pocket placement",
      "colorwayId": null
    },
    {
      "fileResourceId": "b71e0d54-9f2a-4c88-8e13-7a4c9d0e2b6f",
      "folderId": 610,
      "name": "front-artwork-sky-blue.png",
      "note": null,
      "colorwayId": 3307
    }
  ]'
  ```

  ```js JavaScript theme={"dark"}
  const res = await fetch("https://service.my.delogue.com/api/styles/{styleId}/files", {
    method: "POST",
    headers: {
      "Accept": "application/json",
      "X-Auth-Token": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify([
    {
      "fileResourceId": "3f8a9c2e-1b4d-4e77-9a01-6c2d5e8b1f30",
      "folderId": 610,
      "name": "tech-pack.pdf",
      "note": "Rev B — updated pocket placement",
      "colorwayId": null
    },
    {
      "fileResourceId": "b71e0d54-9f2a-4c88-8e13-7a4c9d0e2b6f",
      "folderId": 610,
      "name": "front-artwork-sky-blue.png",
      "note": null,
      "colorwayId": 3307
    }
  ]),
  });
  const { data } = await res.json();
  ```
</CodeGroup>

```json theme={"dark"}
{
  "status": "success",
  "code": "style_files_created",
  "data": [
    {
      "id": 4821,
      "name": "tech-pack.pdf",
      "note": "Rev B — updated pocket placement",
      "state": "active",
      "url": "https://files.example.com/styles/SS26-1042/tech-pack.pdf",
      "position": 0,
      "folderId": 610,
      "folderType": "userDefinedFiles",
      "colorwayId": null,
      "colorwayName": null
    },
    {
      "id": 4822,
      "name": "front-artwork-sky-blue.png",
      "note": null,
      "state": "active",
      "url": "https://files.example.com/styles/SS26-1042/front-artwork-sky-blue.png",
      "position": 1,
      "folderId": 610,
      "folderType": "userDefinedFiles",
      "colorwayId": 3307,
      "colorwayName": "Sky Blue"
    }
  ]
}
```

The response wraps the files in the standard envelope. Each file reports its `folderId`,
`folderType`, `position`, `state`, and — for colourway-specific files — its `colorwayId` and
`colorwayName`.

## Field reference

The fields that matter most when creating or updating a style file:

| Field            | What it means at Delogue                                                                                                                           |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `colorwayId`     | Optional colourway (style colour) to link the file to. Requires the Colorway module, and the file must be a .png, .pdf, .jpg, or .jpeg.            |
| `fileResourceId` | Identifier (GUID) of a file resource already uploaded via the file upload endpoint. Required — a create referencing an empty resource is rejected. |
| `folderId`       | Identifier of the folder to place the file in. Required; the folder must exist on the style.                                                       |
| `name`           | Display name of the file. Must be unique among active files in the same folder.                                                                    |
| `note`           | Optional free-text note on the file.                                                                                                               |

## Roles & permissions

Reading and managing style files requires the **`styles`** permission — style files are part of
the style, not a separate library. Designer (brand) accounts (`CompanyAdmin` / `CompanyUser`)
and the supplier accounts collaborating on the style act through that permission. Every request
is scoped to the caller's organization: a style or file that belongs to another organization
returns `403`, and one that exists in no organization returns `404`.

## 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="Styles" href="/guides/styles">
    Create and manage the styles that files are attached to.
  </Card>

  <Card title="Upload files to a style" href="/api-reference/stylefiles/upload-one-or-more-files-to-a-style">
    Attach uploaded resources to a style: `POST /api/styles/{styleId}/files`.
  </Card>

  <Card title="List a style's folders" href="/api-reference/stylefiles/get-all-file-folders-for-a-style">
    Read a style's folders with files embedded: `GET /api/styles/{styleId}/files`.
  </Card>

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