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

# Apply a settings profile — replace the stored env and reload the fleet

> Apply the profile's active env as the WHOLE stored env band (a key the profile
omits is deleted, save the carried deployment X band), build+swap a fresh serving
epoch under it, persist env-write-LAST, broadcast the reload, and recycle the fleet
for recycle-class diffs. NO request body.

The response is the dedicated ``profileApplyResponse``
``{hot, recycle:[{name, kind, status, generation_before}], fresh:[{name, kind,
generation}], refused:[] on success, fanout}`` — key names + worker identities only,
never env values. ``recycle`` is one line per recycled/timed-out sibling (plus the
applier's own deferred self-exit line when it must self-exit); ``fresh`` is the
per-kind new ready lives observed since the pre-apply snapshot, capacity evidence never
claimed as any target's successor. A refusal (X-band key, dangling ``!ENV``, a recycle-
class diff the deployment shape cannot carry) aborts upfront with a loud 400 naming
the key, before anything is snapshotted, built, or persisted. When the diff carries
serve-affecting recycle keys the applier's OWN recycle is armed as a post-response
graceful self-exit (a Starlette ``BackgroundTask``) — its supervisor respawns it on
the new env. 404 for an absent name.



## OpenAPI

````yaml /openapi.json post /api/config/profiles/{name}/apply
openapi: 3.1.0
info:
  description: The operator HTTP surface served under /api/*.
  title: tai42-skeleton API
  version: 14.0.2
servers: []
security: []
paths:
  /api/config/profiles/{name}/apply:
    post:
      tags:
        - config
      summary: Apply a settings profile — replace the stored env and reload the fleet
      description: >-
        Apply the profile's active env as the WHOLE stored env band (a key the
        profile

        omits is deleted, save the carried deployment X band), build+swap a
        fresh serving

        epoch under it, persist env-write-LAST, broadcast the reload, and
        recycle the fleet

        for recycle-class diffs. NO request body.


        The response is the dedicated ``profileApplyResponse``

        ``{hot, recycle:[{name, kind, status, generation_before}], fresh:[{name,
        kind,

        generation}], refused:[] on success, fanout}`` — key names + worker
        identities only,

        never env values. ``recycle`` is one line per recycled/timed-out sibling
        (plus the

        applier's own deferred self-exit line when it must self-exit); ``fresh``
        is the

        per-kind new ready lives observed since the pre-apply snapshot, capacity
        evidence never

        claimed as any target's successor. A refusal (X-band key, dangling
        ``!ENV``, a recycle-

        class diff the deployment shape cannot carry) aborts upfront with a loud
        400 naming

        the key, before anything is snapshotted, built, or persisted. When the
        diff carries

        serve-affecting recycle keys the applier's OWN recycle is armed as a
        post-response

        graceful self-exit (a Starlette ``BackgroundTask``) — its supervisor
        respawns it on

        the new env. 404 for an absent name.
      operationId: post_api_config_profiles_name_apply
      parameters:
        - in: path
          name: name
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ProfileApplyResponse'
                required:
                  - data
                type: object
          description: Success.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Malformed request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Missing or invalid api key.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Resource not found.
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReloadingError'
          description: The server is applying a config reload; retry shortly.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ProfileApplyResponse:
      description: >-
        The dedicated profile-apply response. ``hot`` are the hot-class diff key

        names; ``recycle`` the recycled/self-deferred worker lines; ``fresh``
        the new

        ready lives seen since the pre-apply snapshot; ``refused`` is empty on
        success

        (any refusal aborts the pipeline before a response is built); ``fanout``
        the

        reload broadcast's fleet summary. Names only — never env values.
      properties:
        fanout:
          $ref: '#/components/schemas/FanoutSummary'
        fresh:
          items:
            $ref: '#/components/schemas/FreshLife'
          title: Fresh
          type: array
        hot:
          items:
            type: string
          title: Hot
          type: array
        recycle:
          items:
            $ref: '#/components/schemas/RecycleEntry'
          title: Recycle
          type: array
        refused:
          items:
            type: string
          title: Refused
          type: array
      required:
        - hot
        - recycle
        - fresh
        - refused
        - fanout
      title: ProfileApplyResponse
      type: object
    Error:
      properties:
        code:
          description: >-
            Stable machine-readable reason a client keys a dedicated error state
            on, present on refusals that opt in (e.g. a 501 not-configured
            refusal). Optional: absent when the error carries only a
            human-readable message.
          type: string
        error:
          type: string
      required:
        - error
      type: object
    ReloadingError:
      properties:
        error:
          const: reloading — the server is applying a config reload; retry shortly
          type: string
        reloading:
          const: true
          type: boolean
      required:
        - error
        - reloading
      type: object
    FanoutSummary:
      description: >-
        The mode-tagged fan-out summary embedded under a mutation response's

        ``fanout`` field.


        ``mode`` selects the shape: ``local-only`` carries only ``note`` (a lone

        worker reached no sibling); ``fleet`` and ``unreachable`` carry the
        per-worker

        broadcast report
        (``op``/``reachable``/``local_only``/``results``/``error``),

        the ``unreachable`` variant having no worker list, only ``error``. The

        mode-variant fields are optional so one model describes every mode
        without

        reshaping any wire payload.
      properties:
        error:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Error
        local_only:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          title: Local Only
        mode:
          title: Mode
          type: string
        note:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Note
        op:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Op
        reachable:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          title: Reachable
        results:
          anyOf:
            - items:
                $ref: '#/components/schemas/FanoutWorkerResult'
              type: array
            - type: 'null'
          default: null
          title: Results
      required:
        - mode
      title: FanoutSummary
      type: object
    FreshLife:
      description: One newly-ready worker life observed since the pre-apply snapshot.
      properties:
        generation:
          title: Generation
          type: integer
        kind:
          title: Kind
          type: string
        name:
          title: Name
          type: string
      required:
        - name
        - kind
        - generation
      title: FreshLife
      type: object
    RecycleEntry:
      description: One recycled or self-deferred worker line in a profile-apply report.
      properties:
        generation_before:
          title: Generation Before
          type: integer
        kind:
          title: Kind
          type: string
        name:
          title: Name
          type: string
        status:
          title: Status
          type: string
      required:
        - name
        - kind
        - status
        - generation_before
      title: RecycleEntry
      type: object
    FanoutWorkerResult:
      description: >-
        One worker's verdict within a multi-worker fan-out report.


        ``payload`` carries a query op's per-worker data; ``error`` a failed
        apply's

        message; ``detail`` the publisher's note for a computed
        missing/departed/

        timed-out verdict. ``outcome`` is the worker's terminal outcome as its
        wire

        string.
      properties:
        detail:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Detail
        error:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Error
        name:
          title: Name
          type: string
        outcome:
          title: Outcome
          type: string
        payload:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          default: null
      required:
        - name
        - outcome
      title: FanoutWorkerResult
      type: object
    JsonValue: {}
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: x-api-key
      type: apiKey

````