Skip to main content

Agent Preferences

Agents — Preferences are per-agent key/value rows for learned and explicit user preferences (timezone, tone, sign-off, formatting). Distinct from Memory — preferences are key-addressable and idempotent on (owner, scope, key). New values for an existing key are archived in a supersedes chain.

All endpoints require authentication via X-API-Key header and the appropriate scope.

Preference Object​

{
  "_id": "pref_abc123",
  "key": "preferred_sign_off",
  "value": "Cheers",
  "description": "How the user signs emails",
  "category": "communication",
  "preferenceSource": "explicit",
  "confidence": 1.0,
  "evidence": "User said 'sign me Cheers' on 2026-05-14.",
  "tags": ["email", "tone"],
  "ownerId": "usr_mn0",
  "organizationId": "org_acme",
  "sharedWith": [],
  "isPublic": false,
  "agentId": null,
  "appId": null,
  "workflowId": "wf_iris",
  "supersedes": null,
  "supersededBy": null,
  "lastUsedAt": "2026-05-17T09:55:00Z",
  "createdAt": "2026-05-15T10:00:00Z",
  "updatedAt": "2026-05-17T10:00:00Z"
}

preferenceSource is one of: explicit, learned, inferred, imported, manual.

GET /api/v1/preferences​

List preferences visible to the caller. Filters by preferenceSource, tag, and full-text search.

Scope: preferences:read

Query Parameters

ParameterTypeRequiredDescription
preferenceSourcestringNoFilter by source kind
tagstringNoSingle-tag filter
searchstringNoFull-text on key + value + evidence
limitintegerNoPage size (default 50)
offsetintegerNoSkip count
scopeobjectNoScope tuple {agentId?, appId?, workflowId?}

POST /api/v1/preferences​

Upsert by (owner, scope, key). Idempotent: writing the same key+value twice is a no-op. Writing a new value for an existing key archives the previous row in the supersedes chain and points supersededBy at the new row.

Scope: preferences:write

Request Body

{
  "key": "preferred_sign_off",
  "value": "Cheers",
  "category": "communication",
  "preferenceSource": "explicit",
  "confidence": 1.0,
  "evidence": "User said 'sign me Cheers' on 2026-05-14.",
  "tags": ["email", "tone"],
  "scope": { "workflowId": "wf_iris" }
}

Response 201 Created

{ "data": { "_id": "pref_abc123" } }

GET /api/v1/preferences/:id​

Fetch a preference by id.

Scope: preferences:read

GET /api/v1/preferences/by-key/:key​

Look up the current preference for a key in the caller's scope (i.e. the row that is not yet superseded).

Scope: preferences:read

PATCH /api/v1/preferences/:id​

Update fields on an existing row in place. Does NOT create a new supersedes-chain entry. Use POST /preferences (set semantics) if you want chain-aware history.

Scope: preferences:write

Request Body — any subset of editable fields:

{
  "value": "Best",
  "category": "communication",
  "confidence": 0.9
}

DELETE /api/v1/preferences/:id​

Hard-delete a single row by id. Does not walk the supersedes chain — use POST /preferences/forget to drop the current row by key.

Scope: preferences:write

Response 204 No Content

POST /api/v1/preferences/forget​

Forget a preference by key. Removes the current (non-superseded) row in the given scope.

Scope: preferences:write

Request Body

{ "key": "preferred_sign_off", "scope": { "workflowId": "wf_iris" } }

scope is optional — defaults to the caller's per-agent context.

POST /api/v1/preferences/:id/share​

Share a preference with one user. Owner / admin only.

Scope: preferences:write

Request Body

{ "userId": "usr_target" }

POST /api/v1/preferences/:id/unshare​

Unshare from one user.

Scope: preferences:write

POST /api/v1/preferences/:id/toggle-public​

Flip isPublic. Owner / admin only.

Scope: preferences:write

PATCH /api/v1/preferences/:id/scope​

Replace the scope tuple. Owner-only.

Scope: preferences:write

Request Body

{ "scope": { "agentId": null, "appId": null, "workflowId": "wf_iris" } }

Python SDK​

from strongly import Strongly

client = Strongly()

# Upsert by key — idempotent on (owner, scope, key).
client.preferences.set(
    key="preferred_sign_off",
    value="Cheers",
    preferenceSource="explicit",
    scope={"workflowId": "wf_iris"},
)

# Read.
current = client.preferences.get_by_key("preferred_sign_off")

# Forget the current row for a key.
client.preferences.forget("preferred_sign_off", scope={"workflowId": "wf_iris"})

Full client surface: list, create, set, retrieve, get_by_key, update, delete, forget, share, unshare, toggle_public, update_scope.

See also​