---
title: "Get the site brief"
method: GET
path: "/api/v1/sites/{slug}/brief"
tags: ["Brief"]
---

# Get the site brief

`GET /api/v1/sites/{slug}/brief`

## Request

- Base URL: `https://api.dotsy.ai`
- URL: `https://api.dotsy.ai/api/v1/sites/{slug}/brief`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

The site brief says what the site is for: `head` holds the purpose, audience, priorities, editing model, design direction and the site's rules & guidelines (`head.rules`), and `notes` holds the free-form notes. `sectionNotes` holds the Design system, Content & CMS and SEO notes that are set. `aiAccess` is what AI agents may do on the site, and `ruleFailures` the failing Rules per section from the last check, which ran at `ruleFailuresCheckedAt` (all three also on the 404 and 409 answers). Add `?page=<content key>` to read one page's brief instead.

A site that has no brief yet answers 404 `brief_not_set`. `hash` changes on every write.

## Path parameters

- `slug` string, required

## Query parameters

- `page` string

## Response `200`

The site brief, or the page brief when `?page=` was sent.

- union: The site brief, or the page brief when the request carried `?page=`.
  - SiteBrief
    - `head` SiteBriefHead, required: The structured top of the site brief. `purpose` is required (5–280 characters).
      - `purpose` string, required
      - `audience` string
      - `kind` 'exploration' | 'production'
      - `priorities` object
        - `seo` 'must' | 'nice' | 'skip'
        - `analytics` 'must' | 'nice' | 'skip'
        - `design` 'must' | 'nice' | 'skip'
        - `mobile` 'must' | 'nice' | 'skip'
      - `editingModel` 'ai' | 'simple-editor' | 'creator'
      - `sections` string[]
      - `design` object
        - `palette` string[]
        - `type` string[]
        - `layout` string
      - `rules` object[]
        - `id` string, required
        - `card` 'intent' | 'design' | 'content' | 'seo', required
        - `text` string, required
        - `level` 'block' | 'warn'
        - `locked` boolean
        - `check` object
          - `type` string, required
      - `updated` string
      - `updatedBy` 'agent' | 'human'
    - `notes` string, nullable, required: The brief's `## Notes` section, or null when it has none.
    - `hash` string: Content hash of the stored brief (changes on every write).
    - `sectionNotes` object: The Design system, Content & CMS and SEO notes that are set (full text). Omitted when none is.
      - `design` string
      - `content` string
      - `seo` string
    - `hasBody` boolean: True when the brief has narrative text beyond the head and notes. Omitted on a site-brief write.
    - `aiAccess` 'viewer' | 'contributor' | 'editor' | 'owner': GET only (also on the 404 `brief_not_set` and 409 `brief_head_corrupt` answers): what AI agents and API keys may do on this site — the effective level, `owner` (Full access) by default.
    - `ruleFailures` object: GET only (also on the 404 and 409 answers): how many Rules failed in each section on the site's last check. Omitted until a check has counted any.
      - `intent` integer, required
      - `design` integer, required
      - `content` integer, required
      - `seo` integer, required
    - `ruleFailuresCheckedAt` integer: GET only, with `ruleFailures`: when that check ran (epoch ms). A Rule added after it has not been checked yet.
  - PageBrief
    - `head` PageBriefHead, required
      - `purpose` string
      - `design` object
        - `direction` string
        - `hero` string
    - `notes` string, nullable, required: The page brief's `## Notes` section, or null when it has none.
    - `hash` string
    - `hasBody` boolean, required

## Other responses

- `400`: `page` is not a usable content key (`invalid_page`).
- `401`: Missing or invalid credentials.
- `403`: The key or token is limited to other sites (`forbidden_site_scope`).
- `404`: No such site (`not_found`), or no brief has been written yet (`brief_not_set`, with `head: null`).
- `409`: The brief's stored head cannot be parsed (`brief_head_corrupt`). Rewrite `_intent/site.md` through the content API.

---

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