---
title: "Add a preference (confirmed from an approver or owner key; a suggestion from a developer key)"
method: POST
path: "/api/v1/mandates/{id}/preferences"
tags: ["lodestar"]
---

# Add a preference (confirmed from an approver or owner key; a suggestion from a developer key)

`POST /api/v1/mandates/{id}/preferences`

## Request

- Base URL: `https://worthune.com`
- URL: `https://worthune.com/api/v1/mandates/{id}/preferences`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Fixed vocabulary: avoid-strategy (optionally until a date), min-value for a strategy, max-annual-conversion, avoid-alternative. Confirmed preferences are enforced by the gate in every cycle, with or without a planner.

## Request body

- object
  - `kind` 'avoid-strategy' | 'min-value' | 'max-annual-conversion' | 'avoid-alternative', required
  - `strategy` string
  - `alternativeId` string
  - `amountUsd` number
  - `until` string, date
  - `note` string

## Response `201`

Created.

- object
  - `ok` unknown, required
  - `preference` Preference, required
    - `id` integer, required
    - `mandateId` integer, required
    - `kind` 'avoid-strategy' | 'min-value' | 'max-annual-conversion' | 'avoid-alternative', required
    - `strategy` string
    - `alternativeId` string
    - `amountUsd` integer
    - `until` string, date
    - `description` string, required: The preference in a sentence.
    - `status` 'suggested' | 'confirmed', required: Only a confirmed preference changes what the gate lets through.
    - `source` 'advisor' | 'planner', required
    - `proposalId` integer, nullable: The rejected proposal it was suggested from.
    - `note` string, nullable
    - `createdBy` string, nullable
    - `confirmedBy` string, nullable
    - `confirmedAt` string, date-time, nullable
    - `createdAt` string, date-time, required

## Other responses

- `400`: Malformed JSON, a body of the wrong shape, or a top-level field that fails its check.
- `401`: No key presented (Authorization: Bearer wk_… or X-Api-Key).
- `402`: Unrecognized or revoked API key.
- `403`: The key's role is below the operation's floor (viewer < developer < owner), the key predates organization support, or the plan lacks the feature. On a sandbox key, also: the cap of 5 active households on create and import, the cap of 1 active Lodestar mandate, and the white-label surfaces (tenant config, embed tokens) and narration or mapping drafts on Worthune's model (they run on your own: a model assigned at /api/v1/model-policy, or x-model-key), which the sandbox does not carry.
- `404`: No such mandate in your organization.
- `409`: The mandate has ended.
- `422`: Not a valid preference (each error has a path).
- `429`: Hourly per-org stateful quota, a per-route durable limit, or the 120 requests/minute per-IP burst backstop.
- `503`: Billing is not configured on this deployment; household resources are disabled rather than served without tenancy (production fail-closed).

---

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