Score a Cycle

Proposed rehearsal cycle payload and score response

POST /v1/cycles

Score a Cycle

cURL

curl --request POST \
  --url https://{host}/v1/cycles \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cycle_id": "20260929T0205",
  "cycle_time": "2026-09-29T02:05:00+09:00",
  "candidates": [
    {
      "gall_id": "example_gallery",
      "post_no": 31900001,
      "title": "Example original title",
      "created_at": "2026-09-29T01:58:12+09:00",
      "extracted_at": "2026-09-29T02:03:40+09:00",
      "source": "keyword",
      "manual_flag": 0,
      "images_in_post": 2
    }
  ],
  "engagement": [
    {
      "gall_id": "example_gallery",
      "post_no": 31900001,
      "observed_at": "2026-09-29T02:04:00+09:00",
      "status": "ok",
      "views": 412,
      "up": 9,
      "down": 1,
      "comment_cnt": 6,
      "rtb_vote": 0
    },
    {
      "gall_id": "example_gallery",
      "post_no": 31899120,
      "observed_at": "2026-09-29T02:04:00+09:00",
      "status": "ok",
      "views": 1875,
      "up": null,
      "down": null,
      "comment_cnt": 21,
      "rtb_vote": 0
    }
  ],
  "candidate_scores": [
    {
      "gall_id": "example_gallery",
      "post_no": 31900001,
      "snapshot_at": "2026-09-29T02:05:00+09:00",
      "recommend_up_cnt": 3,
      "recommend_up_cnt_m": 2,
      "recommend_up_cnt_a": 1,
      "comment_cnt": 2,
      "comment_cnt_m": 1,
      "comment_cnt_a": 0,
      "hit_cnt": 5,
      "hit_cnt_m": 3,
      "hit_cnt_a": 1,
      "dcbest_cnt": 0,
      "dcbest_cnt_m": 0,
      "dcbest_cnt_a": 0,
      "memo_size": 1840,
      "upimg_cnt": 2,
      "upimg_height": 2410
    }
  ],
  "removals": [
    {
      "gall_id": "example_gallery",
      "post_no": 31898050,
      "reason": "hidden",
      "decided_at": "2026-09-29T02:01:10+09:00"
    }
  ]
}
'

200

first_scores

{
  "cycle_id": "20260929T0205",
  "cycle_time": "2026-09-29T02:05:00+09:00",
  "received_at": "2026-09-29T02:05:03+09:00",
  "scored_at": "2026-09-29T02:05:09+09:00",
  "model_version": "m0924-weight0",
  "weights_version": "w-1",
  "counts": {
    "candidates": 1,
    "engagement": 2,
    "candidate_scores": 1,
    "removals": 1,
    "scored_now": 2,
    "waiting": 0,
    "not_scored": 0,
    "results": 2
  },
  "missing_feature_share": 0.11,
  "warnings": [],
  "results": [
    {
      "gall_id": "example_gallery",
      "post_no": 31899120,
      "status": "scored",
      "score": 0.62,
      "scored_at_cycle": "2026-09-29T02:05:00+09:00"
    },
    {
      "gall_id": "example_gallery",
      "post_no": 31900001,
      "status": "scored",
      "score": 0.51,
      "scored_at_cycle": "2026-09-29T02:05:00+09:00"
    }
  ]
}

Proposed rehearsal behavior

DCinside sends new candidates, engagement updates for all pending posts and removals. Surf proposes returning refreshed scores for every pending candidate in the response. Five minutes is the initial cadence proposed for review; it is not an agreed exclusive interval.

This endpoint reference describes the rehearsal proposal. The deployed implementation’s timing and model still need the changes listed in Rehearsal and acceptance.

Request guidance

Field	Meaning
cycle_id	Stable request ID. The existing format is YYYYMMDDTHHMM in KST. Retry the same ID with the same body.
cycle_time	Scheduled time of this cycle, with an explicit offset. The current server enforces five-minute boundaries; confirm cadence before rehearsal.
candidates	All new candidates since the last acknowledged delivery. Send each post’s text once. No candidate-count cap.
engagement	Current readings for every pending candidate, including newly sent candidates. Unknown counters are null.
candidate_scores	Proposed mapping for available admin snapshots. The existing wire shape requires this array, but it may be empty. Review its fields with the delivered model.
removals	Posts leaving the pending pool: saved, hidden, deleted or aged out. DCinside applies the 24-hour filter and sends aged-out removals.

extracted_at means entry into DCinside’s queue. It is the start of the first-score measurement, not the start of a separate wait. Candidate metadata and the exact required-field list remain part of the payload review.

Use the field reference below for proposed types and examples. JSON may be plain or gzip-compressed. Current size and array protections are listed in Conventions; do not truncate the full queue to fit them.

Response and retry semantics

The proposed response contains post IDs, final scores, model and weight versions, scoring times and counts. Per-part predictions are optional. New cycles may change a pending post’s score; retries of the same completed cycle return its original result.

The response deadline is to be agreed. A late response is skipped for that cycle, but its data must still be reconciled. Recover using GET /v1/scores/{cycle_id} or replay the original request. See the worker integration notes for retry budgeting.

Examples below illustrate the proposed contract, not captured outputs from the current placeholder model.

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.

Headers

Content-Encoding · enum<string>

Optional compression. Set to gzip only for a gzip-compressed body; plain JSON is also supported.

Available options: gzip

Body

application/json

Proposed rehearsal wire shape. Required arrays and extra metadata need payload review. Current other-array and request-size protections are engineering limits, not client quotas.

cycle_id · string · required

Idempotency key: the cycle time in KST as YYYYMMDDTHHMM, for example 20260929T0205. The same id with the same body returns the stored response. The same id with a different body returns 409.

Pattern: ^\d{8}T\d{4}$

Example:

"20260929T0205"

cycle_time · string<date-time> · required

Scheduled cycle time with an explicit offset; normalize to KST for cycle_id. Five minutes is proposed initially within the stated 2–5-minute range. The current server enforces five-minute boundaries and rejects future cycles; changing cadence requires implementation support.

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

Example:

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

candidates · object[] · required

All posts that became candidates since the last successful call. Each post is sent once. May be empty. There is no candidate-count cap; the complete JSON body must fit within 16 MiB after decompression. Pending candidates are retained across cycles until removed.

Show child attributes

engagement · object[] · required

One row for every pending candidate, every cycle. Pending means sent in this or an earlier call and not yet in removals. The current 5,000-row cap is an engineering protection, not an agreed business quota; validate it against full-queue delivery.

Maximum array length: 5000

Show child attributes

candidate_scores · object[] · required

Available admin snapshots, when present. Existing wire shape requires the array but permits []. Confirm feature mapping and requiredness with the client and delivered model. The current 5,000-row cap is an engineering protection, not an agreed business quota; validate it against full-queue delivery.

Maximum array length: 5000

Show child attributes

removals · object[] · required

Posts leaving the pending pool since the last successful call. May be empty. The current 5,000-row cap is an engineering protection, not an agreed business quota; validate it against full-queue delivery.

Maximum array length: 5000

Show child attributes

Response

200

application/json

The scores for this cycle.

cycle_id · string · required

Echoed from the request.

Pattern: ^\d{8}T\d{4}$

Example:

"20260929T0205"

cycle_time · string<date-time> · required

Echoed from the request.

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

Example:

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

received_at · string<date-time> · required

Our clock when the call arrived.

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

Example:

"2026-09-29T02:05:03+09:00"

scored_at · string<date-time> · required

Proposed meaning: actual scoring completion time. The current handler records its pre-processing time here; fix and verify before using this field for latency measurement. Measure client receipt time separately.

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

Example:

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

model_version · string · required

Identity of the actual model that produced the results. The current transport adapter uses a Model-0924-like label; that label alone is not proof the delivered artifact is loaded.

Example:

"m0924-weight0"

weights_version · string · required

Weights that actually produced this cycle's scores. Verify that refreshed scores and their version match; do not relabel cached scores.

Example:

"w-1"

counts · object · required

Row counts for this cycle.

Show child attributes

missing_feature_share · number · required

Implementation-specific diagnostic. The current adapter counts missing request counters, not missing values across a verified 62-feature model. It is not a rehearsal acceptance metric.

Required range: 0 <= x <= 1

Example:

0.11

warnings · string[] · required

Implementation warnings. Unknown fields are not guaranteed to be listed. An empty list does not prove model or data readiness.

Example:

[]

results · object[] · required

One result per pending candidate under the proposed refresh policy. Scores may change across new cycles; replay of a completed cycle is unchanged. Removed posts are absent from subsequent cycles.

Show child attributes