Migration map.

channel_create — plan and create a site

New default-image tasks also use a durable completion refresh checkpoint; status exposes an uncertain refresh without resending it.

Current HTTP legacy icon handling rejects iconAssetId before planning or writes, including dry runs. See the legacy-icon preflight and saved-task guidance. New original-image tasks use iconFile; do not rewrite existing task inputs.

Creation response and unknown-outcome behavior are tightened by the current response correction. Unreadable write acknowledgements are not treated as unsent work.

Current file-template behavior supersedes the historical uploader limitation below: see the file-template handoff correction. It is a console handoff, not an implemented automatic import.

The current title rule and task recovery guidance explain emoji and the broader advertised JSON Schema envelope.

See the current correction and older-server guidance before preparing new inputs; keep existing task inputs unchanged during recovery.

Submit the new site's title, design, apps, transaction currency and optional original icon as one workflow. It validates current choices, creates the channel, refreshes credentials, and reads channel detail. To rename an existing site, use channel_settings_apply instead. Read channel_creation_options for the intended category first.

Input

The top-level object and all design variants are strict. Additional fields and null are rejected. Use siteTitle, not title; do not submit an HTTP request body, password, token, or arbitrary URL. The runtime trims the title before fingerprinting; JSON Schema itself does not encode this transform.

App and currency planning

Selected apps must be released/visible and pass the options filter. Planning takes each app's first default FREE pricing model, requires its code to match the app code, and checks all three fees in the selected currency: installation, monthly base, and metered unit. Each must explicitly carry that currency and a zero amount string. A FREE label alone is insufficient. Missing, paid, or unverifiable costs require human console creation; this tool submits no payment.

A platform object fixes currency to its baseCurrency, or to KRW when that field is absent. If platform:null, use the supplied currency or default to KRW. The current account's platform rule takes precedence over a caller's preference.

Examples

The following is an illustrative blank-design plan. Omitted apps use current recommendations; inspect the actual plan and any no-app confirmation result before executing.

{
  "requestId":"example-site-create-001",
  "siteTitle":"Example site",
  "category":"HOMEPAGE",
  "design":{"kind":"blank"},
  "dryRun":true
}

For a catalog design, use the returned template identifier and normally omit appCodes:

{
  "requestId":"example-site-create-002",
  "siteTitle":"Catalog example",
  "category":"HOMEPAGE",
  "design":{"kind":"catalog","templateCode":"template-code-from-options"},
  "dryRun":true
}

The template code is a placeholder, not a known current template. Neither example is a recorded execution. After inspecting a valid plan, submit the same request ID and business inputs with only dryRun changed to false. Select the intended apps and currency from current options, rather than assuming the examples suit the account.

Plan and request mapping

The workflow maps ordinary business inputs to its request body:

Before a real creation or prepared-job resume, current options are reread and the derived plan is compared with the saved plan. This does not reserve options or verify server state atomically. The comparison covers the derived body, not every catalog/pricing field that could change without changing that body.

The HTTP path is POST /seller/api/v1/channels with the account bearer, then POST /seller/api/v2/refresh with the refresh token and no account bearer, then GET /seller/api/v1/channels/{channelCode} with the selected channel bearer. The creation receipt must identify the new channel. The HTTP adapter normalizes a missing/empty channel code from primitiveInvitationCode when available.

Inline icon contract

iconFile.filename is a PNG/JPG/JPEG basename, 1–240 characters, without paths, drive/URL prefixes, colon or controls. Extension matching is case-insensitive at runtime; use lowercase to also satisfy the exported regex, which omits its flag. base64 is canonical original-file base64, 4–1,333,336 characters, without whitespace or a data-URL prefix. Decoded bytes must be nonempty and at most 1,000,000 decimal bytes. The PNG/JPEG structure must match the extension. No resizing, rendering, remote fetching or image-content rewriting occurs. This is separate from the larger marketing image limit.

Do not combine iconFile with iconAssetId or design.kind:file: the workflow returns CREATION_ICON_INPUT_CONFLICT before account access. This cross-field rule and byte validation exceed exported JSON Schema. Invalid files return INVALID_CHANNEL_ICON. The host must configure its resource gateway, bucket and region even for a new icon dry run; URLs and credentials are not tool inputs. Legacy icon IDs return UPLOAD_NOT_CONNECTED before option reads, planning or writes, even for dry runs; the returned link targets the creation screen. Existing prepared journals and any saved location are preserved, not migrated to iconFile. File-template plans and unsent tasks return FILE_TEMPLATE_CONSOLE_REQUIRED without an upload or create. Owner profile-image uploads are outside this creation input.

Before a new icon task, verified account connection, seller, main profile and role bind the operation. New dry runs read options and validate file/configuration but issue no grant, PUT, creation, refresh or job. Real execution issues an account-scoped POST /seller/api/v1/credentials to the resource gateway, without channel/consumer headers, then uploads the unchanged bytes with a checksum. It validates the receipt and supplies its exact location to the composite channel POST. Creation/grant accept 200 or 201 data envelopes; final channel GET requires 200/data, bounded to 2 MiB. Options and owner context are rechecked before creation. The created channel detail uses that channel's bearer after account refresh.

{"requestId":"example-icon-create-001","siteTitle":"Example icon site","category":"CUSTOM_SERVICE","design":{"kind":"blank"},"appCodes":[],"acceptNoApps":true,"iconFile":{"filename":"icon.png","base64":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aDWQAAAAASUVORK5CYII="},"dryRun":true}

This illustrative tiny file is a schema/parser example, not a recorded upload or recommended artwork. Use the user's original file. A successful upload can remain unused if later options, pricing, context or creation checks fail; no object deletion or rollback is performed.

Inputs

Results and completion

A new dry run does not persist a job, despite returning taskId. Its steps are validate, upload_if_needed, create, refresh, and verify. requiredAssets merely lists supplied asset IDs; it does not validate them. An existing job's created:false dry-run field means the dry-run call performs no creation, not that the stored job has never created a channel.

The completed channel contains id, channelCode, title, baseCurrency, optional currentPlan, and the verified iconImageSrc for inline-icon completion. verification.confirmed:true with method:channel_detail confirms the detail ID/code against the receipt and the title/currency against the plan. It does not confirm installed apps, public launch, domain availability, visitor rendering, or payment eligibility. Fresh non-demo completion can return the observed new channel's console home through the shared finalizer. Historical completion suppresses current navigation; neither is a visitor URL.

Saved identity, effects, and recovery

Real execution writes the private job and, after successful refresh, the credential file. The task ID equals the request ID. The fingerprint uses parsed inputs with dryRun:false; input defaults/trim are normalized, while app order and omitted-versus-explicit business fields can still affect identity. Reusing a saved ID with different inputs or connection returns TASK_CONTEXT_CHANGED.

Call task_status with the original ID and taskType:channel-create to inspect progress. To continue the original operation, call task_resume with that same pair:

Historical default-image tasks without a versioned checkpoint retain their prior format. An explicitly recorded unknown completion now stops without refresh; other marker-free tasks still require inspection of their earlier recovery history. New default-image tasks record refresh pending/sent/done; after an acknowledged refresh, only detail verification is retried. task_status returns completion.credentialRefresh as pending, outcome_unknown or acknowledged. Inline-icon jobs retain their existing separate upload/refresh journal.

Inline-icon jobs store file metadata/hash and owner/plan bindings, never the file bytes or temporary upload credentials. The fingerprint uses metadata, including filename and SHA-256; reusing the ID with different bytes is rejected. Status validates the journal/owner without advancing effects. Recovery adds these boundaries:

Fresh icon completion additionally requires exact uploaded location equality and returns iconLocationConfirmed:true, publicRenderingVerified:false. Invalid/inconsistent journals return CHANNEL_CREATION_STATE_INVALID without rewriting previous evidence. Do not edit old jobs to opt into these checkpoints.

If only a new dry run ran, TASK_NOT_FOUND is expected. A successful creation can precede a failed refresh/readback, so an error does not necessarily mean nothing was created. Keep the original ID and known channel; do not delete job state, change its binding, or create under a new ID to bypass an uncertain result. There is no automatic channel deletion/rollback or global server idempotency guarantee. Local task/connection locks do not automatically expire; an operator must inspect abandoned locks before repair.

In hosted mode creation, options, and channel-create recovery are account operations. Subsequent channel work requires a separately authorized selected-channel resource.

Failures and next action

Authentication, HTTP, private-storage, and lock failures follow common results. Plan errors must not be resolved by overwriting saved tasks.

Implementation: src/contracts.ts::inputSchema/planChannel, src/workflow.ts::ChannelWorkflow, src/publ-http.ts, src/papp-pricing.ts, and src/state.ts.

Saved plan replay

An existing matching task's dryRun returns a historical saved plan, with historical:true, replayed:true, phase, taskId and false current verification. It has no current console/action link and does not reread target business state, repeat effects or change the journal. Follow nextStep for a current observation; retain the original task ID for status/resume or uncertain-outcome inspection. A new task keeps normal fresh-plan validation.

nextStep: channels_list with markChannelAs:"RUNNING" is account-scoped and does not guess a channel from its title. Saved body and existingPhase remain; created:false means this dry-run call created nothing. Prepared input-policy checks, journal/account/owner validation and original file input matching remain in force. Saved history does not require new options or certify current upload readiness.

Saved record identity

Apply/dry-run replay and task status/resume bind both the saved ID and saved input requestId to the requested task ID. An intact record stored under another lookup key is also refused with TASK_STATE_UNVERIFIED, before business reads or effects. Keep both records for inspection; do not rename/edit them, use the embedded ID or create a replacement task to bypass refusal. Matching tasks keep their existing validation and recovery rules. Connection/authorization checks may still run; this guard is not a complete record schema or current-state verification.