Agent Preferences API

Overview

The Agent Preferences API stores per-user response-style settings. On every successful update, the platform regenerates a managed STYLE.md file in every agent workspace owned by the user. These preferences are also injected into agent-chat system instructions at send time. Supported response styles are:

concise — brief, direct responses without preamble.
balanced — the default, thorough enough to be useful but concise enough to stay readable.
detailed — full reasoning, context, and edge cases.
custom — driven entirely by custom_instructions.

This namespace is served by the Allternit API data-plane node (http://127.0.0.1:8013 on the same machine, or your paired or provisioned node). The hosted Cloud API at https://api.allternit.com does not route it; it relays only agent sessions, canvases, office and beta research/sessions. See Cloud API.

Base URL

http://127.0.0.1:8013/api

Authentication

All requests must include a valid bearer token in the Authorization header.

Preference object

Field	Type	Description
`response_style`	string	One of `concise`, `balanced`, `detailed`, `custom`.
`custom_instructions`	string	Free-form instructions appended to `STYLE.md`.
`updated_at`	string	ISO 8601 timestamp of the last update.

Endpoints

Get preferences

GET /api/agent-preferences

Returns the caller’s preferences. If no row exists, returns the default style balanced with empty custom instructions.

Example request

curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8013/api/agent-preferences

Example response

{
  "response_style": "detailed",
  "custom_instructions": "Always include concrete code examples when explaining a concept.",
  "updated_at": "2026-08-13T14:22:00Z"
}

Set preferences

PUT /api/agent-preferences

Updates the caller’s preferences. Omitted fields are merged with existing values. After the database update, the gateway best-effort regenerates STYLE.md in every agent workspace the user owns.

Request body

Field	Type	Required	Description
`response_style`	string	No	Must be one of the supported styles.
`custom_instructions`	string	No	Free-form custom instructions.

Example request

curl -X PUT http://127.0.0.1:8013/api/agent-preferences \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "response_style": "detailed",
    "custom_instructions": "Always include concrete code examples when explaining a concept."
  }'

Example response

{
  "response_style": "detailed",
  "custom_instructions": "Always include concrete code examples when explaining a concept.",
  "updated_at": "2026-08-13T14:22:00Z"
}

STYLE.md format

The managed STYLE.md written to each workspace looks like this:

<!-- Managed by Allternit response-style settings.
     This file is regenerated on every settings change and will be
     overwritten — do not hand-edit. -->

# Response Style

Respond in detail. Explain your reasoning, include relevant context, and cover edge cases.

## Custom Instructions

Always include concrete code examples when explaining a concept.

Do not hand-edit STYLE.md. The gateway overwrites it on every preference update.

Error codes

Status	Meaning
`200`	Success.
`400`	Invalid `response_style`.
`401`	Unauthorized.
`500`	Internal server error.

Platform API

Legal

Overview

Agency API (Preview)

LLM Gateway

Agents & Runtime

Work Queue & Deployments

Files, Webhooks & Sandbox

Tools & Connectors

Collaboration & Workflows

Infrastructure & Platform

Canvases

Onboarding

A Labs

Playground

Users & Profiles

Overview

Base URL

Authentication

Preference object

Endpoints

Get preferences

Example request

Example response

Set preferences

Request body

Example request

Example response

STYLE.md format

Error codes

​Overview

​Base URL

​Authentication

​Preference object

​Endpoints

​Get preferences

​Example request

​Example response

​Set preferences

​Request body

​Example request

​Example response

​STYLE.md format

​Error codes

​Related pages

Overview

Base URL

Authentication

Preference object

Endpoints

Get preferences

Example request

Example response

Set preferences

Request body

Example request

Example response

STYLE.md format

Error codes

Related pages