> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.scripe.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings

# Settings & engagement

Read a project's curated settings, its engagement policy, and the
workspace's LinkedIn company pages. Over REST this family is
**read-only by design** — the settings writes exist only on
[MCP](./mcp-tools.md#2-write-tools) behind two-phase confirmation,
because settings text becomes prompt content for future AI generations
and engagement policies act under a LinkedIn identity.

Full schemas: **OpenAPI reference → Settings**.

| Method | Path                    | Scope            | Notes                                         |
| ------ | ----------------------- | ---------------- | --------------------------------------------- |
| GET    | `/v1/settings`          | `workspace:read` | Curated project settings.                     |
| GET    | `/v1/engagement-policy` | `workspace:read` | Engagement defaults + overrides + lock state. |
| GET    | `/v1/company-pages`     | `projects:read`  | LinkedIn company pages in the workspace.      |

Both scopes are grantable to API keys and OAuth tokens alike — see
[auth.md §1.2](./auth.md#12-scopes).

***

## `GET /v1/settings`

Structured fields only: generation-context knobs (language, formality,
length/formatting/emoji preferences), the project tone-of-voice fields,
the workspace custom-instruction state, calendar settings, and content
pillars. The **rendered prompt context is never returned** — you get
the same knobs the dashboard shows, not the compiled instructions.

Two parts of the response are worth calling out:

* **The stored preference integers come with word labels.** The
  length/formatting/emoji preferences are stored as integers whose
  numbers are neither ordinal nor consistent with each other, so
  `context` carries `postLengthPreferenceLabel`,
  `formattingPreferenceLabel` and `emojiPreferenceLabel` — derived
  through the same mapping the generators use. Read the labels; the
  MCP write takes the same words
  ([`update_tone_of_voice`](./mcp-tools.md#28-writing-style-preferences-update_tone_of_voice)).
* **`calendar` includes the recurring posting-time template.**
  `calendar.schedule.slots[]` (each a wall-clock `time` plus its
  `days`) and `postsPerWeek`, expressed in `calendar.effectiveTimezone`
  (always an IANA name — `calendar.timezone` is the raw stored value
  and may be `null` or legacy). This is the template
  `GET /v1/calendar/next-free-slot` walks, and what the MCP
  [`update_posting_schedule`](./mcp-tools.md#27-the-posting-schedule-update_posting_schedule)
  replaces.

## `GET /v1/engagement-policy`

A project's auto-engagement configuration: the like/comment/reshare
defaults (`OFF` | `REQUEST` | `ON`), per-requester overrides, the stored
LinkedIn connection state that determines whether engagement *can* be
enabled, and the plan-lock state — locked workspaces still see what
would unlock.

**Answer from `effective`, not `policy`.** `policy` is the stored row
and it is `null` for most projects — which is not "anything might
happen": activation fails closed, so a project with no row is declined.
`effective` is always present and reports what actually happens right
now, with `source: "policy"` (stored defaults) or `"no_policy"`
(fail-closed default). See
[MCP tools §1.15](./mcp-tools.md#115-is-anything-engaging-as-me--read-effective-not-policy)
for why the distinction is load-bearing.

## `GET /v1/company-pages`

The workspace's LinkedIn company pages — the delta over
`GET /v1/projects`: activation status, **stored** admin-token health
(as of last validation, never a live LinkedIn probe), follower count,
and engagement-policy state.

***

## Writing settings (MCP only)

* [`update_tone_of_voice`](./mcp-tools.md#2-write-tools) — project-level
  tone-of-voice/context writes. Two-phase (the proposal renders the full
  new text next to current values) and restricted to workspace admins.
* [`update_engagement_policy`](./mcp-tools.md#2-write-tools) — sets the
  auto-engagement defaults to `OFF` or `REQUEST` only. Turning a policy
  fully `ON` (autonomous engagement under the project's LinkedIn
  identity) is deliberately dashboard-only. Disarming (all-OFF) is
  always allowed; anything else needs an eligible plan. A LinkedIn
  connection is needed to publish, not to store the policy.
* [`update_positioning` / `update_global_tone_of_voice`](./mcp-tools.md#210-positioning-and-the-org-wide-voice)
  — the WORKSPACE-level positioning documents and the organization-wide
  tone of voice (Business plan). Empty fields write directly; replacing
  text a person already wrote is two-phase via `overwrite: true`.
* [`update_personal_dna`](./mcp-tools.md#210-positioning-and-the-org-wide-voice)
  — ONE brand's personal DNA (who the author is, credibility points,
  opinions & hot takes, stories; the person document behind Brand →
  Positioning → "You"). Same empty-vs-occupied rule and overwrite
  confirmation; `get_personal_dna` is the read side.
* [`update_posting_schedule`](./mcp-tools.md#27-the-posting-schedule-update_posting_schedule)
  — replaces the recurring posting-time template read from
  `GET /v1/settings`. Two-phase, full-state, `calendar:write`.

All but the last require the `settings:write` scope — never implied by
`write` or anything else, so an integration can only reach them if the
user consented to that scope by name.