---
title: "Start Guideline Set Decomposition"
method: POST
path: "/marketing/guideline-sets/{guideline_set_id}/decompositions"
tags: ["marketing-guideline-sets"]
---

# Start Guideline Set Decomposition

`POST /marketing/guideline-sets/{guideline_set_id}/decompositions`

## Request

- Base URL: `https://api.kobaltlabs.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.kobaltlabs.com/marketing/guideline-sets/{guideline_set_id}/decompositions`
- Auth: none declared

Read this set's primary documents and propose requirements from them.

Additional documents are persisted onto the set's own membership first (`_add_members`) — the
reading and the set's configuration are one gesture from here, not two, since a document added
only for this run would leave the *next* reading unable to reproduce what this one saw.

Writes PROPOSED requirements only: no analysis can reach one until a person approves it
(`GuidelineRequirementState.PROPOSED` is excluded everywhere a library is resolved for judging),
so running this against a set an analysis already reads changes nothing about what that analysis
sees until someone acts on what comes back.

## Path parameters

- `guideline_set_id` string, uuid, required

## Request body

- GuidelineSetDecompositionRequest: Trigger a reading of this set's primary documents. Unlike `GuidelineSetWrite`, `additional_documents` here is *added* to the set's membership rather than replacing it — triggering a reading is "also read this while you're at it", not a person re-composing the whole list, and should not require resending every document already configured just to keep them.
  - `auto_determine_supporting_files` boolean
  - `additional_documents` GuidelineSetDocument[]
    - `file_id` string, uuid, required
    - `role` 'primary' | 'supporting', required: What one document contributes to a guideline set. PRIMARY documents are read *for obligations*: every requirement traces to exactly one of them, and `MarketingGuidelineRequirement.file_id` names it. SUPPORTING documents — a brand book, a glossary, a claims-substantiation memo — are read *for context* and produce no requirement of their own. The distinction is not presentational. It decides which documents a product line drags into `gather_candidates`, so filing a glossary as primary is how a definitions list becomes a hundred obligations nobody wrote, and filing a standards document as supporting is how its rules quietly stop being checked.

## Response `201`

Successful Response

- GuidelineSetDecompositionResponse: What starting a reading of a set reports back. Not `DecompositionSummary` — that model's `upload_id` assumes the classic path's one-document shape, which a set-scoped reading never has. This names the row and how many of the set's primary documents it means to read, which is what the confirming dialog needs to say back.
  - `decomposition_id` string, uuid, required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed', required: Lifecycle of one decomposition run.
  - `documents_queued` integer, required
  - `documents_skipped` integer, required
  - `selecting_supporting_documents` boolean

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-05** `eb329fb4c94a`: 2 info
  - added the new optional request property `auto_determine_supporting_files`
  - added the optional property `selecting_supporting_documents` to the response with the `201` status
- **2026-09-02** `425d5b8a3c17`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/kobaltlabs/apis/fastapi/changes/marketing/guideline-sets/:guideline_set_id/decompositions/post.md)

---

[API](https://skmtc.dev/kobaltlabs/apis/fastapi.md) - [All operations](https://skmtc.dev/kobaltlabs/apis/fastapi/llms.txt) - [OpenAPI document](https://skmtc.dev/kobaltlabs/apis/fastapi/revisions/8587332d5e43?raw)