> ## Documentation Index
> Fetch the complete documentation index at: https://surf-dcinside-api.kr.ask.surf/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Weights

> Proposed configuration changes without retraining

<Note>
  **Not in scope for trial.** Client-driven weight changes through this endpoint are outside the current trial integration scope. The trial uses the delivered model with down-vote weight 0.
</Note>

Surf computes the final score, with weights adjustable without retraining. The intended initial configuration has down-vote weight 0. Per-part predictions are optional.

This endpoint proposes versioned configuration changes, taking effect on the next cycle. The activation cycle must be explicit, and every affected score must be computed with the reported version. Re-reading an older completed cycle preserves its original scores and versions.

Before including this endpoint in a later phase, confirm who can change weights and how changes are coordinated. Do not assume per-endpoint credential scope enforcement is already implemented.

Current validation requires non-negative weights and at least one positive value among `views`, `comments` and `up`. `hide` and `deletion` remain zero until the corresponding model support is available. There is no agreed upper bound of 10 on weights. Version-name and note-length protections are implementation choices, described in [Conventions](/conventions#current-service-protections).

Repeating the same version and configuration returns the original acknowledgement; changing a previously used version returns a conflict. Verify refresh behavior and restart durability before enabling client-driven configuration changes.


## OpenAPI

````yaml openapi.json PUT /v1/weights
openapi: 3.0.3
info:
  title: DCinside RTB API
  description: >-
    Proposed contract for DCinside's scoring-only dress rehearsal. Real queue
    candidates go to Surf; DCinside logs would-be picks while operators continue
    publishing. The model does not publish during rehearsal. The intended model
    is the delivered Model 0924 with down-vote weight 0; the deployed
    transport-test adapter is not that artifact. Five-minute cycles, inline
    responses, pending re-scoring, payload details and authentication are Surf
    proposals for confirmation. The response deadline is not yet agreed.
    DCinside's draft first-score target is at least 99% within two cycles of
    queue entry, with no separate scoring wait. This specification describes
    target rehearsal behavior, not deployment readiness. See the rehearsal
    documentation for implementation gaps and acceptance criteria.
  version: 1.1.0-draft
servers:
  - url: https://{host}
    description: Issued by Surf together with the API key.
    variables:
      host:
        default: rtb.example.com
        description: >-
          Host name issued by Surf for the environment (rehearsal or
          production). The default is a placeholder.
security:
  - ApiKey: []
tags:
  - name: Scoring
    description: >-
      Proposed cycle scoring and retrieval for rehearsal; cadence, refresh
      policy and deadline need confirmation.
  - name: Images
    description: >-
      Proposed one-time image transfer; layout and scoring readiness behavior
      need confirmation.
  - name: Outcomes
    description: >-
      Not in scope for trial. Reference for later outcomes-endpoint integration.
      Daily operator outcomes may be shared separately by agreement.
  - name: Weights
    description: >-
      Not in scope for trial. Reference for later client-facing
      weight-management integration. Surf configures the initial trial model and
      weights.
  - name: Health
    description: >-
      Service information; not proof of model readiness, durable state or alert
      delivery.
paths:
  /v1/weights:
    put:
      tags:
        - Weights
      summary: Set Weights
      description: >-
        Not in scope for trial. This client-facing management endpoint is
        reference material for later integration; Surf configures the initial
        trial weights. Proposed versioned weight changes without retraining,
        effective next cycle. Access and activation rules need confirmation.
        Scores must reflect their actual model and weights; the current
        cached-score implementation needs correction before client-driven
        changes are enabled. Non-negative weights with a positive views,
        comments or up weight are current validation rules, not client-agreed
        ranges.
      operationId: putWeights
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WeightsRequest'
            example:
              version: w-1
              weights:
                views: 1
                comments: 0
                up: 0
                downvote_share: 0
              note: 'first trial: views only'
      responses:
        '200':
          description: Accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeightsAck'
              example:
                version: w-1
                first_cycle_time: '2026-09-29T02:10:00+09:00'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    WeightsRequest:
      type: object
      properties:
        version:
          type: string
          pattern: ^[A-Za-z0-9._-]{1,64}$
          example: w-1
          description: >-
            Proposed stable configuration version. Current engineering
            protection: letters, digits, dot, underscore or hyphen, up to 64
            characters. Same version/body can be retried; different
            configuration under that version conflicts.
        weights:
          $ref: '#/components/schemas/WeightSet'
        note:
          type: string
          maxLength: 500
          example: 'first trial: views only'
          description: >-
            Optional annotation; current implementation protection is 500
            characters, not a client-agreed business limit.
      required:
        - version
        - weights
    WeightsAck:
      type: object
      properties:
        version:
          type: string
          example: w-1
          description: >-
            The accepted version, scheduled for first_cycle_time; not
            necessarily active at receipt time.
        first_cycle_time:
          type: string
          format: date-time
          description: The first cycle the weights apply to, which is the next one.
          example: '2026-09-29T02:10:00+09:00'
          pattern: >-
            ^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})$
      required:
        - version
        - first_cycle_time
    WeightSet:
      type: object
      properties:
        views:
          type: number
          minimum: 0
          example: 1
          description: Weight on `p_views`.
        comments:
          type: number
          minimum: 0
          example: 0
          description: Weight on `p_comments`.
        up:
          type: number
          minimum: 0
          example: 0
          description: Weight on `p_up`.
        downvote_share:
          type: number
          minimum: 0
          example: 0
          description: >-
            Weight on the predicted down-vote share. It is subtracted, so send
            it as a positive number.
        hide:
          type: integer
          enum:
            - 0
          example: 0
          description: Reserved for the later hide head. Must be 0 or left out.
        deletion:
          type: integer
          enum:
            - 0
          example: 0
          description: Reserved for the later deletion head. Must be 0 or left out.
      required:
        - views
        - comments
        - up
        - downvote_share
      description: >-
        Publish-score weights. At least one of `views`, `comments` and `up` must
        be above 0.
    Error:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      required:
        - error
    ErrorBody:
      type: object
      properties:
        code:
          type: string
          example: bad_request
          description: Machine-readable code. See Errors.
        message:
          type: string
          example: 2 fields failed validation
          description: Human-readable summary.
        fields:
          type: array
          items:
            $ref: '#/components/schemas/ErrorField'
          description: Every failing field, when the error is about the body.
      required:
        - code
        - message
    ErrorField:
      type: object
      properties:
        path:
          type: string
          example: candidates[0].created_at
          description: Path of the failing field.
        problem:
          type: string
          example: timestamp must include an explicit offset
          description: Description of the validation failure.
      required:
        - path
        - problem
  responses:
    BadRequest:
      description: >-
        Malformed JSON or a request-schema failure. Semantic checks may return
        only the first error; no exhaustive-error guarantee.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: bad_request
              message: 2 fields failed validation
              fields:
                - path: candidates[0].created_at
                  problem: timestamp must include an explicit offset
                - path: engagement[3].views
                  problem: must be a non-negative integer or null
    Unauthorized:
      description: The API key is missing or unknown.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: API key missing or unknown
    Conflict:
      description: The id was already used with a different body. The first body stays.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: cycle_conflict
              message: cycle 20260929T0205 was already received with a different body
    Unprocessable:
      description: >-
        The body is valid JSON and matches the schema, but the values are not
        acceptable. Nothing is stored.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unprocessable
              message: cycle_time cannot be in the future
              fields:
                - path: cycle_time
                  problem: must not be in the future
    ServerError:
      description: >-
        Server failure. Skip late or unusable scores for the decision cycle,
        preserve unacknowledged data and reconcile delivery. Alert delivery must
        be verified separately.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: server_error
              message: internal error
  securitySchemes:
    ApiKey:
      type: apiKey
      name: Authorization
      in: header
      description: >-
        Proposed API key sent as the whole Authorization header value.
        Long-lived credential scope, handoff and rotation need confirmation.
        Per-endpoint scopes are not currently enforced.

````