Conventions

Proposed transport, timestamps, retries and current service protections

Contract status

This is a proposed rehearsal contract. Required fields in OpenAPI describe the proposed wire format; they are not evidence that DCinside has agreed to every field. Existing implementation restrictions are identified below so that they can be resolved before rehearsal.

Base URL and authentication

Surf and DCinside need to confirm the reachable rehearsal host, a long-lived scoped credential, and whether an IP allowlist is practical for the sending machines. rtb.example.com is a placeholder, not a working host.

The current API accepts the key as the whole header value:

Authorization: <api-key>

Credential scope and rotation procedure remain to be agreed. The current key check does not implement per-endpoint scopes; do not assume a 403 scope check is active. /v1/health currently permits unauthenticated access.

Formats

Topic	Proposed convention
Encoding	UTF-8 JSON. Plain JSON and gzip are supported; send Content-Encoding: gzip only when compressed.
Times	RFC 3339 with an explicit offset, including Z for UTC. Normalize to KST for cycle IDs and time-of-day features. A +09:00 wire offset is not mandatory.
Counters	Non-negative integers; null means unknown. Do not substitute zero for an unknown reading.
Post identity	gall_id plus post_no; post numbers are not globally unique.
Field mapping	Reuse the delivered v1.2/v1.3 column names where practical. Additional metadata and required fields need payload review.
Extra fields	The current parser ignores unknown fields without necessarily warning. Confirm any field on which the integration depends.

Cycle interval

We propose five minutes initially, matching 288 daily cycles in DCinside’s acceptance draft. DCinside described a configurable 2–5-minute interval. The current implementation only accepts five-minute boundaries; this is an implementation restriction, not a jointly agreed business requirement. Confirm the interval before rehearsal and support the agreed setting.

The existing wire shape uses the KST cycle time as cycle_id, for example 20260929T0205. Keep that ID stable on retries. The exact ID format remains part of the proposed protocol.

Retries and recovery

For cycles, the proposal is: same ID and same body returns the original completed result; same ID with a different body returns 409 cycle_conflict. GET /v1/scores/{cycle_id} retrieves that result without scoring again. A new cycle may produce new scores for the same pending posts.

Skipping a late score does not mean discarding undelivered candidate data or removals. Retain unacknowledged data until receipt is established by replay, retrieval or reconciliation. Avoid changing a possibly accepted request under the same ID. Cross-cycle recovery and retention rules must be settled and tested before rehearsal.

A response deadline and a retry budget must be agreed separately. The helper client’s 60-second default is a local implementation setting, not an agreed response deadline. There is no automatic 202/polling switch in the current API.

Current service protections

Protection	Current implementation
JSON request body	16 MiB after decompression
New candidates per cycle	No candidate-count cap
Each other cycle array	5,000 rows
Outcomes per request (Not in scope for trial)	5,000 records
Image body	5 MiB
Weight version / note	Version up to 64 characters using letters, digits, ., _, -; note up to 500 characters

These are engineering protections, not client quotas. Validate them against the full queue before rehearsal. If a complete cycle exceeds a protection, change the limit or agree a batch protocol; never silently truncate or sample the queue. Different bodies cannot be split under one cycle ID. Pagination is not currently implemented.

DCinside handles the 24-hour age filter and sends aged-out removals. About 2,200 new posts/day is an estimate; it is not an API limit.