Set Weights

Set Weights

curl --request PUT \
  --url https://{host}/v1/weights \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "version": "w-1",
  "weights": {
    "views": 1,
    "comments": 0,
    "up": 0,
    "downvote_share": 0
  },
  "note": "first trial: views only"
}
'

import requests

url = "https://{host}/v1/weights"

payload = {
    "version": "w-1",
    "weights": {
        "views": 1,
        "comments": 0,
        "up": 0,
        "downvote_share": 0
    },
    "note": "first trial: views only"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    version: 'w-1',
    weights: {views: 1, comments: 0, up: 0, downvote_share: 0},
    note: 'first trial: views only'
  })
};

fetch('https://{host}/v1/weights', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{host}/v1/weights",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'version' => 'w-1',
    'weights' => [
        'views' => 1,
        'comments' => 0,
        'up' => 0,
        'downvote_share' => 0
    ],
    'note' => 'first trial: views only'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{host}/v1/weights"

	payload := strings.NewReader("{\n  \"version\": \"w-1\",\n  \"weights\": {\n    \"views\": 1,\n    \"comments\": 0,\n    \"up\": 0,\n    \"downvote_share\": 0\n  },\n  \"note\": \"first trial: views only\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://{host}/v1/weights")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"version\": \"w-1\",\n  \"weights\": {\n    \"views\": 1,\n    \"comments\": 0,\n    \"up\": 0,\n    \"downvote_share\": 0\n  },\n  \"note\": \"first trial: views only\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{host}/v1/weights")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"version\": \"w-1\",\n  \"weights\": {\n    \"views\": 1,\n    \"comments\": 0,\n    \"up\": 0,\n    \"downvote_share\": 0\n  },\n  \"note\": \"first trial: views only\"\n}"

response = http.request(request)
puts response.read_body

{
  "version": "w-1",
  "first_cycle_time": "2026-09-29T02:10:00+09:00"
}

{
  "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"
      }
    ]
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "API key missing or unknown"
  }
}

{
  "error": {
    "code": "cycle_conflict",
    "message": "cycle 20260929T0205 was already received with a different body"
  }
}

{
  "error": {
    "code": "unprocessable",
    "message": "cycle_time cannot be in the future",
    "fields": [
      {
        "path": "cycle_time",
        "problem": "must not be in the future"
      }
    ]
  }
}

{
  "error": {
    "code": "server_error",
    "message": "internal error"
  }
}

PUT

weights

Set Weights

curl --request PUT \
  --url https://{host}/v1/weights \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "version": "w-1",
  "weights": {
    "views": 1,
    "comments": 0,
    "up": 0,
    "downvote_share": 0
  },
  "note": "first trial: views only"
}
'

import requests

url = "https://{host}/v1/weights"

payload = {
    "version": "w-1",
    "weights": {
        "views": 1,
        "comments": 0,
        "up": 0,
        "downvote_share": 0
    },
    "note": "first trial: views only"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    version: 'w-1',
    weights: {views: 1, comments: 0, up: 0, downvote_share: 0},
    note: 'first trial: views only'
  })
};

fetch('https://{host}/v1/weights', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{host}/v1/weights",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'version' => 'w-1',
    'weights' => [
        'views' => 1,
        'comments' => 0,
        'up' => 0,
        'downvote_share' => 0
    ],
    'note' => 'first trial: views only'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{host}/v1/weights"

	payload := strings.NewReader("{\n  \"version\": \"w-1\",\n  \"weights\": {\n    \"views\": 1,\n    \"comments\": 0,\n    \"up\": 0,\n    \"downvote_share\": 0\n  },\n  \"note\": \"first trial: views only\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://{host}/v1/weights")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"version\": \"w-1\",\n  \"weights\": {\n    \"views\": 1,\n    \"comments\": 0,\n    \"up\": 0,\n    \"downvote_share\": 0\n  },\n  \"note\": \"first trial: views only\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{host}/v1/weights")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"version\": \"w-1\",\n  \"weights\": {\n    \"views\": 1,\n    \"comments\": 0,\n    \"up\": 0,\n    \"downvote_share\": 0\n  },\n  \"note\": \"first trial: views only\"\n}"

response = http.request(request)
puts response.read_body

{
  "version": "w-1",
  "first_cycle_time": "2026-09-29T02:10:00+09:00"
}

{
  "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"
      }
    ]
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "API key missing or unknown"
  }
}

{
  "error": {
    "code": "cycle_conflict",
    "message": "cycle 20260929T0205 was already received with a different body"
  }
}

{
  "error": {
    "code": "unprocessable",
    "message": "cycle_time cannot be in the future",
    "fields": [
      {
        "path": "cycle_time",
        "problem": "must not be in the future"
      }
    ]
  }
}

{
  "error": {
    "code": "server_error",
    "message": "internal error"
  }
}

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.

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. 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.

Authorizations

Authorization

string

header

required

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.

Body

application/json

version

string

required

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.

Pattern: ^[A-Za-z0-9._-]{1,64}$

Example:

"w-1"

weights

object

required

Publish-score weights. At least one of views, comments and up must be above 0.

Show child attributes

note

string

Optional annotation; current implementation protection is 500 characters, not a client-agreed business limit.

Maximum string length: 500

Example:

"first trial: views only"

Response

Accepted.

version

string

required

The accepted version, scheduled for first_cycle_time; not necessarily active at receipt time.

Example:

"w-1"

first_cycle_time

string<date-time>

required

The first cycle the weights apply to, which is the next one.

Pattern: ^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})$

Example:

"2026-09-29T02:10:00+09:00"

Getting Started

Scoring API

Images API

Weights and Outcomes

Operations

Authorizations

Body

Response