---
title: "Update one section of a brief's outline"
method: PATCH
path: "/briefs/{id}/sections/{sectionNumber}"
tags: ["Briefs"]
---

# Update one section of a brief's outline

`PATCH /briefs/{id}/sections/{sectionNumber}`

## Request

- Base URL: `https://next.frase.io/api/v1`
- URL: `https://next.frase.io/api/v1/briefs/{id}/sections/{sectionNumber}`
- Auth: API key in header `X-API-KEY`

Partial update of a single section. Omitted fields keep their value; `null` clears `owned_keywords` only. `expected_updated_at` is required and is the whole BRIEF's `updated_at` from GET /briefs/{id} — pass literal null if that read returned null. Send `expected_heading` to assert which section you believe number N is; the write is refused if the outline was reordered under you.

A brief that was imported carries its structure as an outline and no content plan. Editing one of its sections materialises the plan on first write and persists both projections, so no plan needs to exist first. A brief with neither a plan nor an outline is refused.

## Path parameters

- `id` string, uuid, required
- `sectionNumber` integer, required

## Query parameters

- `dry_run` 'true'

## Request body

- object: At least one patchable field must be present.
  - `expected_updated_at` string, date-time, nullable, required
  - `expected_heading` string
  - `heading` string
  - `key_points` string[]
  - `suggested_word_count` integer
  - `description` string
  - `format_instructions` string
  - `owned_keywords` string[], nullable
  - `assigned_to` 'ai' | 'user'

## Response `200`

The updated section and the brief's new `updated_at`

- object
  - `data` object
    - `id` string, uuid
    - `section_number` integer
    - `section` BriefSection
      - `heading` string
      - `level` 1 | 2 | 3
      - `key_points` string[]
      - `suggested_word_count` integer
      - `description` string, nullable
      - `format_instructions` string, nullable
      - `owned_keywords` string[], nullable
      - `assigned_to` 'ai' | 'user'
      - `parent_title` string, nullable
      - `evidence` object[]
    - `updated_at` string, date-time

## Other responses

- `400`: Validation failed
- `401`: Authentication failed
- `403`: Forbidden - action not allowed on this resource
- `404`: Resource not found
- `409`: One of: the brief changed since you read it (`conflict`); section N is no longer the heading you asserted (`stale_section_heading`); or the brief is generating (`generation_in_progress`).

---

[API](https://skmtc.dev/frase/apis/frase-api.md) · [All operations](https://skmtc.dev/frase/apis/frase-api/llms.txt) · [OpenAPI document](https://skmtc.dev/frase/apis/frase-api/revisions/7fb75d89f7a4?raw)