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

# Change one setting for your organization.

> Send either `{"value": ...}` or the bare value — both are accepted. The
value is validated against the setting's schema before it is stored, and the
updated row is returned. The change applies only to your organization.

Two keys carry an extra check and reject with 422:
`default_user_permissions` must name a permission set that exists in this
org, and `allowed_sign_ins` may not be saved as a list that excludes the
operator making the change — that list filters who may sign in, and the
settings page is behind that sign-in, so there would be no way back in.



## OpenAPI

````yaml /reference/openapi.json put /settings/{key}
openapi: 3.1.0
info:
  title: AgentEye API
  description: >-
    The AgentEye observability API.


    Every path below is relative to `/v1` on your deployment's dashboard origin
    — e.g. `https://app.example.com/v1/sessions`. Authenticate with a scoped API
    key as a bearer token.


    Organization scoping: a key belongs to one organization and acts on it
    automatically. An instance-scoped key selects one per request with the
    `X-AgentEye-Org` header; without it, such a key resolves to the default
    organization, so set it explicitly on a multi-org deployment.
  license:
    name: MIT
    identifier: MIT
  version: 0.0.1-beta.77
servers:
  - url: /v1
    description: This deployment
security:
  - api_key: []
tags:
  - name: Events
    description: Ingest and query the event store.
  - name: Sessions
    description: Agent sessions and their evaluations.
  - name: Evaluations
    description: Evaluation results and re-runs.
  - name: Dashboards
    description: Dashboards and their tiles.
  - name: Queries
    description: Saved SQL and ad-hoc query execution.
  - name: Keys
    description: Mint and manage scoped API keys.
  - name: Users
    description: Dashboard members and access.
  - name: Settings
    description: Operational settings and context-window overrides.
  - name: Permission sets
    description: Named permission roles.
  - name: Alerts
    description: Alert rules and their recipients.
  - name: Issues
    description: Open, triage, assign and resolve issues.
  - name: Audits
    description: Recurring audits and their findings.
  - name: Usage
    description: Organization usage and billing windows.
  - name: Health
    description: Liveness.
  - name: Auth
    description: Describe the key you are calling with.
paths:
  /settings/{key}:
    put:
      tags:
        - Settings
      summary: Change one setting for your organization.
      description: >-
        Send either `{"value": ...}` or the bare value — both are accepted. The

        value is validated against the setting's schema before it is stored, and
        the

        updated row is returned. The change applies only to your organization.


        Two keys carry an extra check and reject with 422:

        `default_user_permissions` must name a permission set that exists in
        this

        org, and `allowed_sign_ins` may not be saved as a list that excludes the

        operator making the change — that list filters who may sign in, and the

        settings page is behind that sign-in, so there would be no way back in.
      operationId: update_setting
      parameters:
        - name: key
          in: path
          description: The setting key, as listed by `GET /settings/schema`.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema: {}
        required: true
      responses:
        '200':
          description: The updated setting.
        '401':
          description: Missing, unknown, or disabled key.
        '403':
          description: The key lacks `settings:write`.
        '404':
          description: No such setting key.
        '422':
          description: >-
            The value failed the setting's validation, names a permission set
            that does not exist, or would lock the caller out of sign-in.
      security:
        - api_key: []
components:
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      description: >-
        A scoped AgentEye API key. Mint one in the dashboard under Settings →
        API keys, or with `POST /v1/keys`. Each endpoint names the permission it
        requires; a key without it gets 403 and a `required_permission` field
        naming what was missing.

````