---
title: "Add Guideline Set Document"
method: POST
path: "/marketing/guideline-sets/{guideline_set_id}/documents"
tags: ["marketing-guideline-sets"]
---

# Add Guideline Set Document

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

## 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}/documents`
- Auth: none declared

Put one document into the set, leaving the rest of its membership alone.

A pair with the DELETE below, and neither is `PUT /{id}`. That route replaces the whole set —
name, description, guidance, documents *and* live pages — which is right for the form where
somebody is composing the lot by hand and wrong for a chip somebody clicked: a one-click remove
that resent the whole set would overwrite whatever another tab had changed since the page
loaded, and would delete and re-insert every website row to no purpose. `_add_members` already
exists for exactly this reason on the reading path.

Idempotent. A document already in the set keeps the role it has, for the reason `_add_members`
gives: a collision here is a race with another edit, and the first edit's answer is the safer
one to keep.

## Path parameters

- `guideline_set_id` string, uuid, required

## Request body

- 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 `200`

Successful Response

- GuidelineSetSummary: One guideline set, its documents, and what it is attached to.
  - `guideline_set_id` string, uuid, required
  - `name` string, required
  - `description` string, nullable, required
  - `extraction_guidance` string, nullable
  - `documents` GuidelineSetDocumentSummary[], required
    - `file_id` string, uuid, required
    - `filename` string, nullable, 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.
    - `ordinal` integer, required
  - `websites` GuidelineSetWebsiteSummary[]
    - `website_id` string, uuid, required
    - `url` string, required
    - `title` string, nullable, required
    - `note` string, nullable, required
    - `added_by_agent` boolean
  - `preset_ids` string[], required
  - `active_requirement_count` integer, required
  - `total_requirement_count` integer, required
  - `proposed_requirement_count` integer

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-05** `eb329fb4c94a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/kobaltlabs/apis/fastapi/changes/marketing/guideline-sets/:guideline_set_id/documents/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)