用一个安全任务开始
契约 v0.4。所有业务路径按组织成员实时鉴权;模拟任务不会连接付费上游或创建生产订单。
参考效果 · 方仔沙盒 fixture256 × 256 的隔离验收样例,仅用于说明渲染结果形态;使用下面的 Playground 可运行自己的安全模拟任务。 立即试跑 ↗- 每个业务写入都带稳定的
idempotencyKey,重试不会创建第二个任务。 - 模拟任务使用
simulate:figure,只在当前组织创建可回读对象。 - 资产链接受控并显示 7 天失效时间;参考估价不能直接下单。
真实请求示例
创建一个模拟任务
FigureGeneration 的开发者输入固定为公开 HTTPS 人物参考图和脸型枚举;已验证普通成员可在 Dashboard 创建自己的 Key;本例需选择 tasks:write 与 tasks:read。把 API Key 放在服务端环境变量中,浏览器端不要暴露密钥。
curl -X POST 'https://api-prod.unicus.taoz.app/v1/tasks?organizationId=org_team_test' \
-H "Authorization: Bearer $UNICUS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"type":"simulate:figure","payload":{"image_url":"https://files.example.com/fixture.jpg","face_shape":"round"},"idempotencyKey":"playground-20261107-01"}'服务端示例
把任务 ID 留在你的服务里
Legnext 的 quickstart 采用“提交一次、保存 ID、再轮询同一任务”的路径;UNICUS 也要求把密钥和任务 ID 留在受控服务端。
const response = await fetch("https://api-prod.unicus.taoz.app/v1/tasks?organizationId=org_team_test", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.UNICUS_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
type: "simulate:figure",
payload: { image_url: "https://files.example.com/fixture.jpg", face_shape: "round" },
idempotencyKey: "quickstart-safe-01",
}),
});
if (!response.ok) throw new Error(`UNICUS request failed: ${response.status}`);
const task = await response.json();
console.log(task.id); // persist this ID before polling
// On success, task.result contains io_url, glb_url, production_ready, checksFigureGeneration
从照片生成 IO 和 GLB
已开通真实生成的环境接受公开 HTTPS 照片地址和脸型 round、chubby 或 square。请求需有 tasks:write;读取任务需 tasks:read,下载文件需 assets:read。服务端按配置预占 Credits,成功后结算一次,确认失败则释放。未开通的环境返回 figure_generation_disabled。
curl -X POST 'https://api-prod.unicus.taoz.app/v1/figures?organizationId=org_team_test' \
-H "Authorization: Bearer $UNICUS_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: figure-photo-01' \
-d '{"image_url":"https://images.example.com/person.jpg","face_shape":"round"}'收到任务后保存 id,再查询同一任务。201 为新建,200 为原请求回读,202 为已保存并等待队列恢复。遇到响应丢失时沿用原幂等键;受理不明会显示 running / reconciling,应查询原任务。succeeded 后的 io_url、glb_url 和检查附件均为需要鉴权的受控下载地址,文件在创建任务 7 天后失效。此入口仅生成模型。
固定组合
预览与模型估价
两条接口分别组合人仔生成与渲染、或人仔生成与参考估价。请求仍只接受照片、脸型、可选肤色和固定组合参数;价格与 Credits 由服务端配置,调用方不能提交供应商地址、金额或输出开关。预览返回 IO、GLB、渲染图和不含运费的参考价;估价只返回模型与参考价。参考价不能下单,也没有有效期。保存组合 taskId,网络中断时沿用原幂等键读取同一任务;上游受理不明会进入 reconciling,不会新建第二条任务。组合 worker 尚未配置的环境返回 figure_composition_disabled。
curl -X POST 'https://api-prod.unicus.taoz.app/v1/figures/preview?organizationId=org_team_test' \
-H "Authorization: Bearer $UNICUS_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: figure-preview-01' \
-d '{"image_url":"https://images.example.com/person.jpg","face_shape":"round","packaging":0}'curl -X POST 'https://api-prod.unicus.taoz.app/v1/figures/estimate?organizationId=org_team_test' \
-H "Authorization: Bearer $UNICUS_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: figure-estimate-01' \
-d '{"image_url":"https://images.example.com/person.jpg","face_shape":"round","packaging":0}'InstructionGeneration
为模型生成网页说明书
已开通说明书生成的环境接受同组织已成功生成的本地 task_id,或公开 HTTPS 的 IO 文件地址,两种来源任选其一。auto 生成步骤和视角,semi-auto 仅生成视角。此接口始终异步,需 tasks:write;新请求返回 202 后保存任务 id,用 tasks:read 查询同一任务。
curl -X POST 'https://api-prod.unicus.taoz.app/v1/instructions?organizationId=org_team_test' \
-H "Authorization: Bearer $UNICUS_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: manual-model-01' \
-d '{"source":{"io_url":"https://models.example.com/design.io"},"instruction_mode":"auto"}'Credits 按服务端价格预占,成功结算一次,确认失败则释放。文件解析或模型检查失败会记录在任务 error 中。检查附带的诊断文件经核验后提供受控下载链接,需 assets:read,并在任务创建 7 天后失效;文件不可用时会标明原因。成功结果的 web_url 可直接打开原说明书网页,它的有效期遵循上游约定。未开通的环境返回 instruction_generation_disabled。
ModelRendering
从模型生成图片
已开通模型渲染的环境接受同组织已成功生成的本地 task_id,或公开 HTTPS 的 IO 地址,两种来源任选其一。需 tasks:write;服务端预占 Credits,成功结算一次,确认失败则释放。默认角度为 [-8,13],分辨率为 [1024,1024];每个分辨率值须为 64 至 4096 的整数。
curl -X POST 'https://api-prod.unicus.taoz.app/v1/renders?organizationId=org_team_test' \
-H "Authorization: Bearer $UNICUS_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: render-model-01' \
-d '{"source":{"io_url":"https://models.example.com/design.io"},"angle":[-8,13],"resolution":[1024,1024],"mode":"async"}'async 新请求返回 202,同键回读返回 200。sync 最多等待 20 秒观察同一任务:成功返回 200,确认失败返回 422,仍在处理则返回 202。切换 async 与 sync 时沿用原幂等键和参数,不会创建第二个任务。保存 id 并用 tasks:read 继续查询;队列恢复或状态读取暂时失败也沿用这个 id。成功的 image_url 是需 assets:read 的受控下载地址,文件在任务创建 7 天后失效。width、height 表示实际图片尺寸,可能与请求不同。未开通的环境返回 model_rendering_disabled。
任务生命周期
创建、回读、保留
收到任务后先保存 id,说明书始终返回异步任务。
轮询 GET /v1/tasks/:id,直到 succeeded 或 failed;模型生成返回 IO/GLB,说明书返回 web_url,渲染返回 image_url。
下载文件使用受控资产和明确失效时间;说明书网页有效期依上游约定。
展开完整 OpenAPI 3.1 契约
openapi: 3.1.0
info:
title: UNICUS API
version: 0.4.0
description: Organization-scoped一期 contract. Simulation, FigureGeneration, asynchronous InstructionGeneration and ModelRendering are separate capabilities. Real generation is available only when explicitly enabled by the deployment; real partner acceptance is recorded separately from mock verification.
servers:
- url: https://api-prod.unicus.taoz.app
description: Registered UNICUS API origin; verify target health and HTTPS before customer use.
# Customer operations accept either a Better Auth browser session or an
# organization-scoped Bearer API key. Operations that require an administrator
# or the deployment control plane override this default below.
security:
- sessionCookie: []
- apiKeyBearer: []
paths:
/v1/renders:
post:
summary: Render a model with bounded synchronous observation
description: >-
Requires tasks:write for API Keys. Source is exactly one local succeeded
FigureGeneration task_id from this organization or a public HTTPS
io_url. Local IDs resolve to the immutable supplier figure ID. A positive
deployment-configured Credits price is reserved atomically with one
compute:render task. All supplier computation is asynchronous. mode=sync
observes the same durable task for at most 20 seconds; it never runs or
resubmits computation. Switching async to sync with the same idempotency
key returns or observes the original task without another reservation.
Angle values default to [-8,13] and normalize modulo 360, preserving
negative remainders; resolution defaults to [1024,1024]. Returned width
and height are actual supplier dimensions and may differ from the request.
Save the task id and poll GET /v1/tasks/{id}. Success follows RenderResult
only after controlled image copying and verification. Files expire at
task creation plus seven days; retries do not extend retention. Confirmed
success settles once and failure releases once. Unknown acceptance remains
running/reconciling without a second partner POST. Customer task-event
mutation and arbitrary supplier callback or price fields are forbidden.
parameters:
- { $ref: '#/components/parameters/OrganizationId' }
- name: Idempotency-Key
in: header
required: false
description: Required here or as idempotencyKey in the body; both values must match when supplied together.
schema: { type: string, minLength: 1, maxLength: 256 }
requestBody:
required: true
content: { application/json: { schema: { $ref: '#/components/schemas/RenderRequest' } } }
responses:
'202': { description: 'Original durable task still pending, newly accepted asynchronously, or waiting for queue recovery. Save the returned task id.', content: { application/json: { schema: { $ref: '#/components/schemas/Task' } } } }
'200': { description: 'Original idempotent async task or successful sync observation; no new reservation', content: { application/json: { schema: { $ref: '#/components/schemas/Task' } } } }
'422': { description: Confirmed failed task observed in sync mode, content: { application/json: { schema: { $ref: '#/components/schemas/Task' } } } }
'400': { description: Invalid source structure or parameters; model parsing is deferred to the task }
'402': { description: Insufficient available Credits }
'403': { description: Organization membership or tasks:write scope required }
'404': { description: Local source task is not an accessible succeeded figure in this organization }
'409': { description: Conflicting idempotency payload }
'503': { description: ModelRendering disabled or business store unavailable; no task or reservation created }
/v1/instructions:
post:
summary: Generate an asynchronous web instruction manual
description: >-
Requires tasks:write for API Keys. Source is exactly one local succeeded
FigureGeneration task_id from this organization or a public HTTPS
io_url. Local source IDs are resolved to the figure's immutable supplier
ID after checking organization, type and successful completion. Model
downloading, parsing and checks happen asynchronously after acceptance;
invalid-model or model-check-failed is reported as the task's failed
outcome, not as a synchronous model-validation HTTP error. This
task error follows InstructionFailure. Diagnostic files in
error.details.checks[].files use authenticated controlled asset links
after copy verification; temporary delivery errors remain pending.
Copied diagnostic files expire at task creation plus seven days;
unavailable or expired diagnostics expose no supplier download URLs.
The model failure's terminal outcome releases Credits once, including
when diagnostic attachments are explicitly unavailable. This
operation has no mode field and is always asynchronous. A positive
deployment-configured Credits price is reserved atomically with one
compute:instruction task, settled once on success or released on
confirmed failure. Unknown acceptance never triggers a second partner
submission. Save the task id and poll GET /v1/tasks/{id}. A successful
result contains the partner's web_url for a browser instruction page;
it is not a PDF or a physical-production order. The upstream web page's
expiry is not implied by the platform's seven-day downloadable-file
policy. Customer task-event mutation is forbidden for this task type.
parameters:
- { $ref: '#/components/parameters/OrganizationId' }
- name: Idempotency-Key
in: header
required: false
description: Required here or as idempotencyKey in the body; both values must match when supplied together.
schema: { type: string, minLength: 1, maxLength: 256 }
requestBody:
required: true
content: { application/json: { schema: { $ref: '#/components/schemas/InstructionRequest' } } }
responses:
'202': { description: Asynchronous task and Credits reservation accepted. Save the returned task id even when X-Queue-Recovery is pending., content: { application/json: { schema: { $ref: '#/components/schemas/Task' } } } }
'200': { description: Original idempotent task; no new reservation, content: { application/json: { schema: { $ref: '#/components/schemas/Task' } } } }
'400': { description: Invalid source structure, mode, fields or idempotency key; model parsing is deferred to the task }
'402': { description: Insufficient available Credits }
'403': { description: Organization membership or tasks:write scope required }
'404': { description: Local source task is not an accessible succeeded figure in this organization }
'409': { description: Conflicting idempotency payload }
'503': { description: InstructionGeneration disabled or business store unavailable; no task or reservation created }
/v1/figures/preview:
post:
summary: Run the fixed Figure preview combination
description: >-
Requires tasks:write. This combination composes FigureGeneration,
ModelRendering and a reference (non-shipping) estimate. The request
accepts only the documented figure, angle, resolution and packaging
fields; supplier IDs, prices and output flags are server-owned. The
executor reserves the configured Credits for each child step exactly
once, releases all reservations on a confirmed failure, and settles
them once on overall success. The returned durable composition task is
the only retry handle; an unknown upstream acceptance is reconciled
by querying the saved child task and never by creating a second one.
A missing composition worker returns 503 without creating a task or
reservation. Successful output links are authenticated,
organization-scoped `/v1/assets/{id}/content` paths; supplier and
object-store URLs are rejected. Price excludes shipping and cannot
authorize an order.
parameters:
- { $ref: '#/components/parameters/OrganizationId' }
- name: Idempotency-Key
in: header
required: false
description: Required here or as idempotencyKey in the body; both values must match when supplied together.
schema: { type: string, minLength: 1, maxLength: 256 }
requestBody:
required: true
content: { application/json: { schema: { $ref: '#/components/schemas/FigurePreviewRequest' } } }
responses:
'202': { description: 'Durable preview composition accepted; save taskId and poll GET /v1/tasks/{id}.', content: { application/json: { schema: { $ref: '#/components/schemas/FigureCompositionResult' } } } }
'200': { description: Original idempotent composition replay; no new reservation, headers: { X-Idempotent-Replay: { description: "Set to true when the response replays the original composition task.", schema: { type: string, enum: ["true"] } } }, content: { application/json: { schema: { $ref: '#/components/schemas/FigureCompositionResult' } } } }
'400': { description: Invalid composition fields or mismatched idempotency keys }
'402': { description: Insufficient available Credits for a child step }
'403': { description: Organization membership or tasks:write scope required }
'409': { description: Original idempotency key has a different request }
'503': { description: Composition worker or business store unavailable; no task or reservation created }
/v1/figures/estimate:
post:
summary: Run the fixed Figure model and product estimate combination
description: >-
Requires tasks:write. This combination composes FigureGeneration and
a reference quote without rendering. The reference price excludes
shipping, has no expiry and cannot be used to place an order. The
executor reserves the configured FigureGeneration Credits exactly once
and releases them on a confirmed failure. Price, currency and output
URLs are server-owned; callers cannot supply supplier endpoints or
charges. Unknown upstream acceptance is reconciled through the saved
child task and never retried by creating another task. A missing
composition worker returns 503 without creating a task or reservation.
Successful output links are authenticated, organization-scoped
`/v1/assets/{id}/content` paths; supplier and object-store URLs are
rejected.
parameters:
- { $ref: '#/components/parameters/OrganizationId' }
- name: Idempotency-Key
in: header
required: false
description: Required here or as idempotencyKey in the body; both values must match when supplied together.
schema: { type: string, minLength: 1, maxLength: 256 }
requestBody:
required: true
content: { application/json: { schema: { $ref: '#/components/schemas/FigureEstimateRequest' } } }
responses:
'202': { description: 'Durable estimate composition accepted; save taskId and poll GET /v1/tasks/{id}.', content: { application/json: { schema: { $ref: '#/components/schemas/FigureCompositionResult' } } } }
'200': { description: Original idempotent composition replay; no new reservation, headers: { X-Idempotent-Replay: { description: "Set to true when the response replays the original composition task.", schema: { type: string, enum: ["true"] } } }, content: { application/json: { schema: { $ref: '#/components/schemas/FigureCompositionResult' } } } }
'400': { description: Invalid composition fields or mismatched idempotency keys }
'402': { description: Insufficient available Credits }
'403': { description: Organization membership or tasks:write scope required }
'409': { description: Original idempotency key has a different request }
'503': { description: Composition worker or business store unavailable; no task or reservation created }
/v1/figures:
post:
summary: Submit FigureGeneration with fixed IO and GLB delivery
description: >-
Requires tasks:write for API Keys. Accepts a public HTTPS photo URL and
reserves the deployment-configured positive Credits price atomically
with one compute:figure task. The caller cannot select a price, partner
callback, output flags or partner execution mode. Both IO and GLB are
generated asynchronously. Save the returned task id and poll
GET /v1/tasks/{id}; upstream acceptance is not task success. Terminal
success requires controlled copying and verification of both files and
any check attachments. Files expire seven days after task creation.
A confirmed failure releases the reservation; success settles it once.
Unknown acceptance remains running/reconciling and never triggers a
second upstream POST. Customer task-event writes are forbidden for this
task type. This operation does not render or place a production order.
parameters:
- { $ref: '#/components/parameters/OrganizationId' }
- name: Idempotency-Key
in: header
required: false
description: Required here or as idempotencyKey in the body. If both are supplied they must match. Reuse the original key after a lost response.
schema: { type: string, minLength: 1, maxLength: 256 }
requestBody:
required: true
content: { application/json: { schema: { $ref: '#/components/schemas/FigureRequest' } } }
responses:
'201': { description: Task and Credits reservation created, content: { application/json: { schema: { $ref: '#/components/schemas/Task' } } } }
'200': { description: Original idempotent task; no new reservation, content: { application/json: { schema: { $ref: '#/components/schemas/Task' } } } }
'202': { description: Durable task and reservation accepted; queue recovery pending. Save the returned id and poll it., content: { application/json: { schema: { $ref: '#/components/schemas/Task' } } } }
'400': { description: Invalid request, unsupported fields or mismatched idempotency keys }
'402': { description: Insufficient available Credits }
'403': { description: Organization membership or tasks:write scope required }
'409': { description: Original idempotency key has a different request }
'503': { description: FigureGeneration disabled or business store unavailable; no task or reservation created }
/v1/tasks:
post:
summary: Create an asynchronous task
description: Simulation task types and the fixed authorized sandbox:render-example are accepted from the organization-scoped task endpoint. The sandbox example only renders the registered immutable test model at fixed settings. Generic upstream:* and reserved compute:figure/compute:instruction/compute:render types are rejected; typed figure/instruction/render routes enforce atomic Credits reservation, and production writes require the authorized quote/order flow.
parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/TaskRequest' }
responses:
'201': { description: Created, content: { application/json: { schema: { $ref: '#/components/schemas/Task' } } } }
'200': { description: Existing idempotent task returned, content: { application/json: { schema: { $ref: '#/components/schemas/Task' } } } }
'409': { description: Idempotency payload conflict }
get:
summary: List organization tasks
description: Returns the newest tasks visible to the authenticated organization. Reading history never creates, retries, or advances a task.
parameters: [{ $ref: '#/components/parameters/OrganizationId' }, { $ref: '#/components/parameters/ListLimit' }]
responses:
'200':
description: Task history
content:
application/json:
schema:
type: object
required: [tasks]
properties:
tasks:
type: array
items: { $ref: '#/components/schemas/Task' }
'400': { description: Invalid limit }
/v1/tasks/{id}:
get:
summary: Read a task
parameters: [{ $ref: '#/components/parameters/OrganizationId' }, { $ref: '#/components/parameters/Id' }]
responses:
'200': { description: Task, content: { application/json: { schema: { $ref: '#/components/schemas/Task' } } } }
'404': { description: Not found }
/v1/tasks/{id}/attempts:
get:
summary: Read durable task attempts
description: Organization-scoped attempt history records worker retries and terminal errors; it never creates a second task.
parameters: [{ $ref: '#/components/parameters/OrganizationId' }, { $ref: '#/components/parameters/Id' }, { $ref: '#/components/parameters/ListLimit' }]
responses: { '200': { description: Attempt history }, '404': { description: Not found } }
/v1/tasks/{id}/callbacks:
get:
summary: Read task callback delivery log
description: Organization-scoped readback of durable callback delivery attempts. Reading this log never retries or changes the task result.
parameters: [{ $ref: '#/components/parameters/OrganizationId' }, { $ref: '#/components/parameters/Id' }, { $ref: '#/components/parameters/ListLimit' }]
responses: { '200': { description: Callback deliveries }, '404': { description: Not found } }
/v1/tasks/{id}/events:
post:
security:
- sessionCookie: []
summary: Apply one durable task event
description: Event IDs are organization scoped. Replays are no-ops and late lower-rank states cannot overwrite terminal results.
parameters: [{ $ref: '#/components/parameters/OrganizationId' }, { $ref: '#/components/parameters/Id' }, { $ref: '#/components/parameters/WebhookSignature' }]
requestBody:
required: true
content: { application/json: { schema: { $ref: '#/components/schemas/EventRequest' } } }
responses: { '202': { description: Event applied }, '200': { description: Event replay }, '404': { description: Not found }, '409': { description: Event ID fingerprint conflict } }
/v1/internal/organizations/{organizationId}/callbacks/{id}/redeliver:
post:
summary: Operator-only callback redelivery
description: Resets a failed or pending customer callback outbox row. Requires the deployment operator token and never changes the underlying task result.
security:
- operatorToken: []
parameters:
- { name: organizationId, in: path, required: true, schema: { type: string } }
- { name: id, in: path, required: true, schema: { type: string } }
- { $ref: '#/components/parameters/OperatorId' }
responses: { '202': { description: Callback queued }, '401': { description: Operator token required }, '404': { description: Not found } }
/v1/internal/organizations/{organizationId}/production-capability:
put:
summary: Enable or disable production capability
description: Operator-only control-plane operation. Requires the deployment operator token, an explicit operator ID, approval reference and idempotent operation ID; it is never authorized by a customer session or API key.
security:
- operatorToken: []
parameters:
- { name: organizationId, in: path, required: true, schema: { type: string } }
- { $ref: '#/components/parameters/OperatorId' }
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [enabled, operationId, approvalReference]
properties:
enabled: { type: boolean }
operationId: { type: string, minLength: 1 }
approvalReference: { type: string, minLength: 1 }
responses: { '200': { description: Updated production capability, content: { application/json: { schema: { $ref: '#/components/schemas/Balance' } } } }, '400': { description: Approval or operator ID required }, '401': { description: Operator token required }, '409': { description: Idempotency conflict } }
/v1/quotes:
post:
summary: Create a reference or production quote
parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
requestBody:
required: true
content: { application/json: { schema: { $ref: '#/components/schemas/QuoteRequest' } } }
responses: { '201': { description: Quote, content: { application/json: { schema: { $ref: '#/components/schemas/Quote' } } } } }
/v1/quotes/{id}:
get:
summary: Read a quote
parameters: [{ $ref: '#/components/parameters/OrganizationId' }, { $ref: '#/components/parameters/Id' }]
responses: { '200': { description: Quote, content: { application/json: { schema: { $ref: '#/components/schemas/Quote' } } } }, '404': { description: Not found } }
/v1/orders:
post:
summary: Place an order from a valid production quote
description: Reference estimates cannot be ordered. Fiat is reserved atomically and cannot go below the configured minimum (default zero).
parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
requestBody:
required: true
content: { application/json: { schema: { $ref: '#/components/schemas/OrderRequest' } } }
responses:
'201': { description: Order, content: { application/json: { schema: { $ref: '#/components/schemas/Order' } } } }
'200': { description: Existing idempotent order, content: { application/json: { schema: { $ref: '#/components/schemas/Order' } } } }
'409': { description: Quote expired or insufficient balance }
/v1/orders/{id}:
get:
summary: Read an order
parameters: [{ $ref: '#/components/parameters/OrganizationId' }, { $ref: '#/components/parameters/Id' }]
responses: { '200': { description: Order, content: { application/json: { schema: { $ref: '#/components/schemas/Order' } } } }, '404': { description: Not found } }
/v1/orders/{id}/callbacks:
get:
summary: Read order callback delivery log
description: Organization-scoped readback of durable order callback delivery attempts. Reading this log never retries or changes the order result.
parameters: [{ $ref: '#/components/parameters/OrganizationId' }, { $ref: '#/components/parameters/Id' }, { $ref: '#/components/parameters/ListLimit' }]
responses: { '200': { description: Callback deliveries }, '404': { description: Not found } }
/v1/orders/{id}/events:
post:
security:
- sessionCookie: []
summary: Apply a durable production or logistics event
description: Organization-scoped event IDs are idempotent; order statuses advance monotonically and terminal conflicts are rejected.
parameters: [{ $ref: '#/components/parameters/OrganizationId' }, { $ref: '#/components/parameters/Id' }]
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/OrderEventRequest' } } } }
responses: { '202': { description: Event applied }, '200': { description: Event replay }, '409': { description: Event conflict } }
/v1/combinations:
post:
summary: Create a fixed instruction-plus-production combination
description: Creates an organization-scoped durable combination. Set reserve=true for the production-capable path; the operation is idempotent by idempotencyKey.
parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/CombinationRequest' } } } }
responses:
'201': { description: Combination, content: { application/json: { schema: { $ref: '#/components/schemas/Combination' } } } }
'200': { description: Idempotent replay, content: { application/json: { schema: { $ref: '#/components/schemas/Combination' } } } }
'409': { description: Insufficient balance or idempotency conflict }
/v1/combinations/{id}:
get:
summary: Read a fixed combination
parameters: [{ $ref: '#/components/parameters/OrganizationId' }, { $ref: '#/components/parameters/Id' }]
responses: { '200': { description: Combination, content: { application/json: { schema: { $ref: '#/components/schemas/Combination' } } } }, '404': { description: Not found } }
/v1/combinations/{id}/events:
post:
security:
- sessionCookie: []
summary: Advance a fixed combination step
description: Instruction must succeed before production; terminal success/failure settles the reserved accounts once.
parameters: [{ $ref: '#/components/parameters/OrganizationId' }, { $ref: '#/components/parameters/Id' }]
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/CombinationEventRequest' } } } }
responses:
'202': { description: Combination updated, content: { application/json: { schema: { $ref: '#/components/schemas/Combination' } } } }
'200': { description: Idempotent event replay, content: { application/json: { schema: { $ref: '#/components/schemas/Combination' } } } }
'409': { description: Transition or balance conflict }
/v1/balance:
get:
summary: Read organization balances
parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
responses: { '200': { description: Balance, content: { application/json: { schema: { $ref: '#/components/schemas/Balance' } } } } }
/v1/billing/ledger:
get:
summary: Read the organization ledger
description: Organization-scoped readback of immutable balance operations; no customer write is exposed.
parameters: [{ $ref: '#/components/parameters/OrganizationId' }, { name: limit, in: query, required: false, schema: { type: integer, minimum: 1, maximum: 500 } }]
responses:
'200':
description: Ledger entries
content:
application/json:
schema:
type: object
required: [entries]
properties:
entries:
type: array
items: { $ref: '#/components/schemas/LedgerEntry' }
/v1/billing/top-ups:
post:
summary: Record an approved offline top-up
description: Admin/owner session only. Requires approval and operator references; operationId is idempotent.
security:
- sessionCookie: []
parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TopUpRequest' } } } }
responses: { '201': { description: Recorded }, '200': { description: Idempotent replay } }
/v1/billing/exchange:
post:
summary: Exchange fiat to Credits
description: Admin/owner session only. One-way exchange in one database transaction with an approved rate snapshot.
security:
- sessionCookie: []
parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ExchangeRequest' } } } }
responses: { '201': { description: Exchanged }, '409': { description: Insufficient balance } }
/v1/billing/refunds:
post:
summary: Refund to the original account
description: Admin/owner session only. Refunds are bounded by the original settle/debit operation and are idempotent.
security:
- sessionCookie: []
parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/RefundRequest' } } } }
responses: { '201': { description: Refunded }, '409': { description: Refund exceeds original operation } }
/v1/billing/policy:
put:
summary: Set reviewed balance policy
description: Admin/owner session only. Defaults remain zero and post-pay is rejected until separately approved.
security:
- sessionCookie: []
parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/BalancePolicyRequest' } } } }
responses: { '200': { description: Updated balance policy } }
/v1/assets:
get:
summary: List organization file assets
description: Organization-scoped lifecycle readback ordered newest first. Optional status filtering supports pending, available or expired assets. Use the opaque nextCursor to continue older records; the cursor is bound to the organization and status filter. The response never exposes an uncontrolled object-store URL.
parameters: [{ $ref: '#/components/parameters/OrganizationId' }, { name: limit, in: query, required: false, schema: { type: integer, minimum: 1, maximum: 500, default: 100 } }, { name: status, in: query, required: false, description: Filter by lifecycle status, schema: { type: string, enum: [pending, available, expired] } }, { name: cursor, in: query, required: false, description: Opaque nextCursor from the previous page; omit for the newest page., schema: { type: string, maxLength: 4096 } }]
responses:
'200':
description: Asset list
content:
application/json:
schema:
type: object
required: [assets]
properties:
assets:
type: array
items: { $ref: '#/components/schemas/Asset' }
nextCursor: { type: string, description: Opaque continuation cursor; empty when no older records remain. }
'400': { description: Invalid limit, status filter or cursor }
post:
summary: Register an upstream file for controlled copying
description: Registration remains pending until the object-store copy validates the file. Source URLs reject credentials and private hosts.
parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
requestBody:
required: true
content: { application/json: { schema: { $ref: '#/components/schemas/AssetRequest' } } }
responses:
'201':
description: Pending asset
content: { application/json: { schema: { $ref: '#/components/schemas/Asset' } } }
'200':
description: Existing idempotent asset
content: { application/json: { schema: { $ref: '#/components/schemas/Asset' } } }
'400': { description: Invalid source URL }
/v1/assets/{id}:
get:
summary: Read asset lifecycle
parameters: [{ $ref: '#/components/parameters/OrganizationId' }, { $ref: '#/components/parameters/Id' }]
responses:
'200':
description: Asset lifecycle
content: { application/json: { schema: { $ref: '#/components/schemas/Asset' } } }
'404': { description: Not found }
/v1/assets/{id}/content:
get:
summary: Download an available asset through the controlled delivery path
description: Requires organization membership or an organization API key. The object-store gateway URL is never returned; expired, pending and cross-organization assets are denied.
parameters: [{ $ref: '#/components/parameters/OrganizationId' }, { $ref: '#/components/parameters/Id' }]
responses:
'200': { description: Binary asset content }
'404': { description: Asset or object content not found }
'409': { description: Asset is pending or unavailable }
'410': { description: Asset expired }
'503': { description: Controlled delivery unavailable or content integrity failure }
/v1/api-keys:
get:
summary: List own API keys (admins can list organization keys)
description: Member session returns only own metadata; admin/owner sessions return organization metadata and canManageOrganizationKeys=true. Newest first by createdAt then id; nextCursor continues older records until empty. Cursor positions are bound to organization and current member/admin visibility, never grant access. New inserts do not shift older pages. No bearer access. Secret values are never returned after creation.
security:
- sessionCookie: []
parameters: [{ $ref: '#/components/parameters/OrganizationId' }, { name: limit, in: query, required: false, schema: { type: integer, minimum: 1, maximum: 500, default: 100 } }, { name: cursor, in: query, required: false, description: Opaque nextCursor from the previous page; omit to read latest keys., schema: { type: string, maxLength: 4096 } }]
responses: { '200': { description: 'Metadata keys, nextCursor (empty at end), and canManageOrganizationKeys' }, '400': { description: Invalid limit or cursor } }
post:
summary: Create an organization API key
description: Verified current member session creates a key owned by that member. Omitted/null scopes default to read-only; an empty or unknown scope set is rejected. Store the no-store one-time secret once; the server stores only a digest. Bearer credentials cannot manage keys.
security:
- sessionCookie: []
parameters: [{ $ref: '#/components/parameters/OrganizationId' }]
requestBody:
required: true
content: { application/json: { schema: { $ref: '#/components/schemas/APIKeyRequest' } } }
responses: { '201': { description: Created key and one-time secret } }
/v1/api-keys/{id}:
delete:
summary: Revoke an organization API key
description: Members revoke only their own keys; admin/owner sessions can revoke any key in their organization. Foreign or other-member keys return 404. Revocation is immediate and idempotent.
security:
- sessionCookie: []
parameters: [{ $ref: '#/components/parameters/OrganizationId' }, { $ref: '#/components/parameters/Id' }]
responses: { '204': { description: Revoked }, '404': { description: Not found } }
components:
securitySchemes:
sessionCookie: { type: apiKey, in: cookie, name: better-auth.session_token, description: Better Auth HttpOnly browser session cookie. }
apiKeyBearer: { type: http, scheme: bearer, bearerFormat: UNICUS_API_KEY, description: Organization-scoped customer API key. Each call requires its granted resource scope and the verified creator current membership. Removal/rejoining does not reactivate old keys. No key/member/organization management, financial administration, upstream event writes or operator access. }
operatorToken: { type: apiKey, in: header, name: X-UNICUS-Operator-Token, description: Deployment-injected operator capability. Pair with X-UNICUS-Operator-ID; never expose it to customers or browsers. }
parameters:
OrganizationId: { name: organizationId, in: query, required: true, schema: { type: string } }
Id: { name: id, in: path, required: true, schema: { type: string } }
ListLimit: { name: limit, in: query, required: false, description: Maximum number of evidence records to return; defaults to 100., schema: { type: integer, minimum: 1, maximum: 500, default: 100 } }
WebhookSignature: { name: X-UNICUS-Signature, in: header, required: false, description: Required when UNICUS_WEBHOOK_SECRET is configured; HMAC over timestamp and raw body., schema: { type: string } }
OperatorId: { name: X-UNICUS-Operator-ID, in: header, required: true, description: Approved operator identity recorded in the audit trail., schema: { type: string, minLength: 1 } }
schemas:
RenderRequest:
type: object
additionalProperties: false
required: [source]
properties:
source:
oneOf:
- type: object
additionalProperties: false
required: [task_id]
properties:
task_id: { type: string, minLength: 1, maxLength: 256, description: "Local succeeded FigureGeneration task ID in the same organization; not a supplier ID." }
- type: object
additionalProperties: false
required: [io_url]
properties:
io_url: { type: string, format: uri, maxLength: 8192, description: "Public HTTPS IO URL; parsing and model checks are asynchronous." }
angle:
type: array
minItems: 2
maxItems: 2
default: [-8, 13]
description: "Two finite degrees values normalized modulo 360 with negative remainders preserved. Signed zero canonicalizes to zero."
items: { type: number }
resolution:
type: array
minItems: 2
maxItems: 2
default: [1024, 1024]
items: { type: integer, minimum: 64, maximum: 4096 }
mode: { type: string, enum: [async, sync], default: async, description: "sync observes the original task for at most 20 seconds; supplier computation is always asynchronous. Excluded from idempotent task identity." }
idempotencyKey: { type: string, minLength: 1, maxLength: 256, description: "Required unless supplied in the Idempotency-Key header." }
callbackUrl: { type: string, format: uri, description: "Optional customer terminal-notification target; not a supplier callback." }
RenderResult:
type: object
required: [simulated, upstream_task_id, image_url, asset_id, sha256, size_bytes, expires_at, width, height]
properties:
simulated: { type: boolean, const: false }
upstream_task_id: { type: string }
image_url: { type: string, description: "Authenticated same-origin /v1/assets/{id}/content link. Never a supplier URL or object-store locator." }
asset_id: { type: string }
sha256: { type: string, pattern: '^[a-fA-F0-9]{64}$' }
size_bytes: { type: integer, minimum: 1, maximum: 104857600 }
expires_at: { type: string, format: date-time, description: "Fixed at task creation plus seven days." }
width: { type: integer, minimum: 1, maximum: 4096, description: "Actual image width; may be smaller or swapped relative to the request." }
height: { type: integer, minimum: 1, maximum: 4096, description: "Actual image height; may be smaller or swapped relative to the request." }
InstructionRequest:
type: object
additionalProperties: false
required: [source]
properties:
source:
oneOf:
- type: object
additionalProperties: false
required: [task_id]
properties:
task_id: { type: string, minLength: 1, maxLength: 256, description: "Local succeeded FigureGeneration task ID in the current organization, never a caller-supplied supplier ID." }
- type: object
additionalProperties: false
required: [io_url]
properties:
io_url: { type: string, format: uri, maxLength: 8192, description: "Public HTTPS IO URL; parsing and model checks are asynchronous." }
instruction_mode: { type: string, enum: [auto, semi-auto], default: auto, description: "auto generates steps and views; semi-auto generates only views." }
idempotencyKey: { type: string, minLength: 1, maxLength: 256, description: "Required unless supplied in the Idempotency-Key header." }
callbackUrl: { type: string, format: uri, description: "Optional customer terminal-notification target; not a partner callback." }
InstructionResult:
type: object
required: [simulated, upstream_task_id, web_url]
properties:
simulated: { type: boolean, const: false }
upstream_task_id: { type: string }
web_url: { type: string, format: uri, description: "Partner-hosted HTTPS web instruction manual. Its expiry is governed by the upstream agreement, not the downloadable-asset retention period." }
InstructionFailure:
type: object
required: [code, message]
description: Safe asynchronous instruction failure. Diagnostic-file retention applies only to copied files and never defines the successful hosted instruction page's expiry.
properties:
code: { type: string, description: "Includes invalid-model, model-check-failed, instruction-failed or a controlled local instruction validation error." }
message: { type: string, description: "Platform-generated error message; no raw supplier prose or download locators." }
details:
type: object
properties:
checks:
type: array
maxItems: 16
description: At most 32 diagnostic files in total across the check records.
items:
type: object
required: [item, passed, message, files]
properties:
item: { type: string, enum: [collision, disconnected, not-producible] }
passed: { type: boolean }
message: { type: string, description: "Platform-generated explanation of the typed check fact." }
files: { type: array, maxItems: 32, items: { type: string, description: "Authenticated same-origin platform asset content link after verified delivery. Never a supplier URL." } }
attachment_delivery: { type: string, enum: [available, expired, unavailable-invalid-source, unavailable-invalid-checks, unavailable-ownership-mismatch], description: "Present when diagnostic files were supplied. Unavailable or expired delivery exposes no download links." }
assets:
type: object
description: Verified diagnostic-file metadata keyed by platform asset ID; omitted when there are no diagnostic files.
additionalProperties:
type: object
required: [asset_id, sha256, size_bytes, expires_at]
properties:
asset_id: { type: string }
sha256: { type: string, pattern: '^[a-fA-F0-9]{64}$' }
size_bytes: { type: integer, minimum: 1, maximum: 104857600 }
expires_at: { type: string, format: date-time }
expires_at: { type: string, format: date-time, description: "Diagnostic-file deadline fixed at task creation plus seven days. Does not describe the hosted web_url." }
FigureEstimateRequest:
type: object
additionalProperties: false
required: [image_url, face_shape]
properties:
image_url: { type: string, format: uri, maxLength: 8192, description: "Public HTTPS photo URL without credentials, private IP literal or fragment." }
face_shape: { type: string, enum: [round, chubby, square] }
skin_color: { type: string, enum: [light-nougat, reddish-brown, dark-nougat, brown, auto], description: "Defaults to light-nougat for chubby and auto otherwise. Chubby accepts only light-nougat." }
packaging: { type: integer, enum: [0, 1, 2], default: 0, description: "Reference packaging selector: 0 simple, 1 standard, 2 gift box." }
mode: { type: string, enum: [async, sync], default: async, description: "Sync observes the same durable composition; it never creates another child task." }
idempotencyKey: { type: string, minLength: 1, maxLength: 256, description: "Required unless supplied in the Idempotency-Key header." }
callbackUrl: { type: string, format: uri, description: "Optional customer notification destination, kept separate from partner callbacks." }
FigurePreviewRequest:
type: object
additionalProperties: false
required: [image_url, face_shape]
properties:
image_url: { type: string, format: uri, maxLength: 8192, description: "Public HTTPS photo URL without credentials, private IP literal or fragment." }
face_shape: { type: string, enum: [round, chubby, square] }
skin_color: { type: string, enum: [light-nougat, reddish-brown, dark-nougat, brown, auto], description: "Defaults to light-nougat for chubby and auto otherwise. Chubby accepts only light-nougat." }
angle: { type: array, minItems: 2, maxItems: 2, items: { type: number }, default: [-8, 13], description: "Render angles [x, y]; values normalize modulo 360." }
resolution: { type: array, minItems: 2, maxItems: 2, items: { type: integer, minimum: 64, maximum: 4096 }, default: [1024, 1024] }
packaging: { type: integer, enum: [0, 1, 2], default: 0, description: "Reference packaging selector: 0 simple, 1 standard, 2 gift box." }
mode: { type: string, enum: [async, sync], default: async, description: "Sync observes the same durable composition; it never creates another child task." }
idempotencyKey: { type: string, minLength: 1, maxLength: 256, description: "Required unless supplied in the Idempotency-Key header." }
callbackUrl: { type: string, format: uri, description: "Optional customer notification destination, kept separate from partner callbacks." }
FigureCompositionResult:
type: object
required: [kind, status, taskId, figureTaskId]
properties:
kind: { type: string, enum: [estimate, preview] }
status: { type: string, enum: [queued, running, succeeded, failed, reconciling] }
taskId: { type: string, description: "Durable composition task identifier; poll the same task after a lost response." }
figureTaskId: { type: string }
renderTaskId: { type: string, nullable: true }
price: { type: integer, minimum: 0, nullable: true, description: "Reference price excluding shipping; display-only and never an order credential." }
currency: { type: string, nullable: true }
ioUrl: { type: string, nullable: true, description: "Controlled same-origin IO asset link after verified delivery." }
glbUrl: { type: string, nullable: true, description: "Controlled same-origin GLB asset link after verified delivery." }
imageUrl: { type: string, nullable: true, description: "Controlled same-origin rendered image link after verified delivery." }
width: { type: integer, minimum: 1, nullable: true }
height: { type: integer, minimum: 1, nullable: true }
productionReady: { type: boolean, nullable: true }
checks: { type: array, description: "Platform-generated checks. When files are present, each file is an authenticated same-origin /v1/assets/{id}/content link scoped to the current organization; supplier and object-store URLs are rejected.", items: { type: object, additionalProperties: true } }
FigureRequest:
type: object
additionalProperties: false
required: [image_url, face_shape]
properties:
image_url: { type: string, format: uri, maxLength: 8192, description: "Public HTTPS photo URL without credentials, private IP literal or fragment." }
face_shape: { type: string, enum: [round, chubby, square] }
skin_color: { type: string, enum: [light-nougat, reddish-brown, dark-nougat, brown, auto], description: "Defaults to light-nougat for chubby and auto otherwise. Chubby accepts only light-nougat." }
idempotencyKey: { type: string, minLength: 1, maxLength: 256, description: "Required unless supplied in the Idempotency-Key header." }
callbackUrl: { type: string, format: uri, description: "Optional customer notification destination, kept separate from partner callbacks." }
FigureResult:
type: object
required: [simulated, upstream_task_id, io_url, glb_url, production_ready, checks, assets, expires_at]
properties:
simulated: { type: boolean, const: false }
upstream_task_id: { type: string }
io_url: { type: string, description: "Authenticated same-origin /v1/assets/{id}/content link. Never a supplier URL." }
glb_url: { type: string, description: "Authenticated same-origin /v1/assets/{id}/content link." }
production_ready: { type: boolean }
checks:
type: array
items:
type: object
required: [item, passed, message, files]
properties:
item: { type: string, enum: [collision, disconnected, not-producible, part-stock] }
passed: { type: boolean }
message: { type: string }
files: { type: array, items: { type: string, description: "Controlled authenticated asset content link." } }
assets:
type: object
description: Asset identifiers mapped to verified delivery metadata. No supplier URLs or object-store keys.
additionalProperties:
type: object
required: [asset_id, sha256, size_bytes, expires_at]
properties:
asset_id: { type: string }
sha256: { type: string, pattern: '^[a-fA-F0-9]{64}$' }
size_bytes: { type: integer, minimum: 1, maximum: 104857600 }
expires_at: { type: string, format: date-time }
expires_at: { type: string, format: date-time }
TaskRequest:
type: object
required: [type, payload, idempotencyKey]
properties:
type: { type: string, description: "simulate:figure and simulate:render are isolated. sandbox:render-example renders only the registered immutable model in the controlled Fangzai test adapter and returns simulated=false with its upstream task ID; no production order is created. sandbox:order-read is a fixed synthetic order GET probe." }
payload: { type: object, additionalProperties: true }
idempotencyKey: { type: string, minLength: 1 }
callbackUrl: { type: string, format: uri, description: Optional customer callback target; production deployments must use HTTPS. }
Task:
type: object
description: Organization-scoped durable task. Result and error are populated by the simulation or upstream adapter and are read-only task outcomes.
required: [id, organizationId, type, idempotencyKey, status, upstreamState, payload, createdAt, updatedAt]
properties:
id: { type: string }
organizationId: { type: string }
type: { type: string }
idempotencyKey: { type: string }
status: { type: string, enum: [queued, running, reconciling, succeeded, failed] }
upstreamState: { type: string, description: Adapter state such as not-sent, simulated, accepted or reconciling. }
callbackUrl: { type: string, format: uri, nullable: true }
payload: { type: object, additionalProperties: true }
result: { type: object, additionalProperties: true, nullable: true, description: "Structured simulation or upstream result when available. compute:figure terminal success follows FigureResult; compute:instruction terminal success follows InstructionResult; compute:render terminal success follows RenderResult. Running checkpoints are resumable metadata, not delivered files. sandbox:render-example succeeds only after controlled asset delivery and returns simulated=false, upstream_task_id, asset_id, expires_at, sha256, dimensions and same-origin image_url. Pending delivery does not indicate file success; retries preserve the original retention deadline." }
error: { type: object, additionalProperties: true, nullable: true, description: "Structured failure detail when the task fails. compute:instruction uses InstructionFailure, including copied diagnostic-file metadata and explicit attachment delivery status when present." }
createdAt: { type: string, format: date-time }
updatedAt: { type: string, format: date-time }
TaskAttempt: { type: object, required: [id, organizationId, taskId, attempt, status], properties: { id: { type: string }, organizationId: { type: string }, taskId: { type: string }, attempt: { type: integer, minimum: 1 }, status: { type: string, enum: [running, succeeded, failed] }, error: { type: object }, startedAt: { type: string, format: date-time }, finishedAt: { type: string, format: date-time } } }
EventRequest: { type: object, required: [eventId, fingerprint, status], properties: { eventId: { type: string }, fingerprint: { type: string }, status: { type: string, enum: [queued, running, succeeded, failed] }, upstreamState: { type: string }, result: { type: object }, error: { type: object } } }
QuoteRequest:
type: object
description: >-
Create a reference estimate or a supplier-derived production quote.
Production pricing owns amount, currency and validity; caller-supplied
values for those fields are retained only for legacy compatibility and
are ignored when the supplier adapter is configured. The public quote
selectors are top-level fields. Existing clients may keep them inside
the source envelope.
required: [source]
properties:
source: { type: object, additionalProperties: true }
amount: { type: integer, minimum: 0, deprecated: true, description: "Legacy caller field; supplier-derived pricing wins." }
currency: { type: string, deprecated: true, description: "Legacy caller field; supplier-derived pricing wins." }
shippingIncluded: { type: boolean, description: "Set true for a settlement quote that includes shipping; false creates a non-orderable reference estimate." }
shipping:
type: object
description: "Required for production-capable quotes; omitted from reference-quote supplier calls."
required: [recipient_name, phone, country, province, city, postal_code, address_line1]
properties:
recipient_name: { type: string }
phone: { type: string }
email: { type: string }
country: { type: string, enum: [CN, US] }
province: { type: string }
city: { type: string }
postal_code: { type: string }
address_line1: { type: string }
address_line2: { type: string }
packaging: { type: integer, enum: [0, 1, 2], default: 0, description: "0 simple, 1 standard, 2 gift box." }
expedite: { type: boolean, default: false }
withInstructionCard: { type: boolean, default: false }
Quote:
type: object
description: Organization-scoped reference or settlement quote. Reference estimates cannot be used to create orders. A settlement quote whose supplier checks report productionReady=false remains available for review but cannot authorize an order until a new ready quote is obtained.
required: [id, organizationId, currency, source, amount, shippingIncluded, productionReady, createdAt]
properties:
id: { type: string }
organizationId: { type: string }
currency: { type: string }
source: { type: object, additionalProperties: true }
amount: { type: integer, minimum: 0 }
shippingIncluded: { type: boolean }
productionReady: { type: boolean, description: Supplier model-readiness result; false does not downgrade a shipping settlement quote into a reference estimate. }
validUntil: { type: string, format: date-time, nullable: true }
supplierQuoteId: { type: string, description: Supplier quote provenance for production pricing }
breakdown:
nullable: true
description: Supplier price breakdown; may be an object or list
oneOf:
- { type: object, additionalProperties: true }
- { type: array, items: { type: object, additionalProperties: true } }
checks:
nullable: true
description: Supplier model and production checks; preserves supplier shape
oneOf:
- { type: object, additionalProperties: true }
- { type: array, items: { type: object, additionalProperties: true } }
createdAt: { type: string, format: date-time }
OrderRequest: { type: object, required: [quoteId], properties: { quoteId: { type: string }, idempotencyKey: { type: string }, callbackUrl: { type: string, format: uri, description: Optional customer callback target; production deployments must use HTTPS. } }, description: The organization-scoped order and balance reservation are persisted before an internal order-flow task may submit the persisted quote source upstream. }
Order:
type: object
description: Organization-scoped order created only from a usable production quote; balance reservation and order state are durable.
required: [id, organizationId, quoteId, status, currency, amount, createdAt, updatedAt]
properties:
id: { type: string }
organizationId: { type: string }
quoteId: { type: string }
status: { type: string, enum: [repairing, in-production, shipped, delivered, failed] }
currency: { type: string }
amount: { type: integer, minimum: 0 }
upstreamOrderId: { type: string, nullable: true }
callbackUrl: { type: string, format: uri, nullable: true }
tracking: { type: object, additionalProperties: true, nullable: true }
createdAt: { type: string, format: date-time }
updatedAt: { type: string, format: date-time }
OrderEventRequest: { type: object, required: [eventId, fingerprint, status], properties: { eventId: { type: string }, fingerprint: { type: string }, status: { type: string, enum: [repairing, in-production, shipped, delivered, failed] }, upstreamOrderId: { type: string }, tracking: { type: object, additionalProperties: true } } }
CombinationRequest: { type: object, required: [idempotencyKey, credits, fiat], properties: { idempotencyKey: { type: string }, credits: { type: integer, minimum: 0 }, fiat: { type: integer, minimum: 0 }, reserve: { type: boolean, description: Required for the production-capable path } } }
Combination:
type: object
description: Organization-scoped fixed instruction-plus-production workflow and its single settlement outcome.
required: [id, organizationId, idempotencyKey, instructionStatus, productionStatus, outcome, credits, fiat, settlementCount, createdAt]
properties:
id: { type: string }
organizationId: { type: string }
idempotencyKey: { type: string }
instructionStatus: { type: string, enum: [pending, succeeded, failed] }
productionStatus: { type: string, enum: [pending, succeeded, failed] }
outcome: { type: string, enum: [pending, succeeded, failed] }
credits: { type: integer, minimum: 0 }
fiat: { type: integer, minimum: 0 }
settlementCount: { type: integer, minimum: 0 }
createdAt: { type: string, format: date-time }
CombinationEventRequest: { type: object, required: [step, status], properties: { step: { type: string, enum: [instruction, production] }, status: { type: string, enum: [pending, succeeded, failed] } } }
Balance: { type: object, properties: { organizationId: { type: string }, creditsAvailable: { type: integer }, fiatAvailable: { type: integer }, creditsReserved: { type: integer }, fiatReserved: { type: integer }, minimumCredits: { type: integer }, minimumFiat: { type: integer }, creditLimitCredits: { type: integer }, creditLimitFiat: { type: integer }, postpayEnabled: { type: boolean }, productionEnabled: { type: boolean } } }
LedgerEntry:
type: object
description: Immutable organization-scoped balance operation record.
required: [id, organizationId, account, kind, amount, operationId, referenceType, referenceId, metadata, createdAt]
properties:
id: { type: string }
organizationId: { type: string }
account: { type: string, enum: [fiat, credits] }
kind: { type: string, enum: [credit, debit, reserve, release, settle, exchange, refund] }
amount: { type: integer, minimum: 0 }
operationId: { type: string }
referenceType: { type: string }
referenceId: { type: string }
metadata: { type: object, additionalProperties: true }
createdAt: { type: string, format: date-time }
AssetRequest: { type: object, required: [sourceUrl], properties: { sourceUrl: { type: string, format: uri }, taskId: { type: string }, expiresAt: { type: string, format: date-time } } }
Asset:
type: object
description: Organization-scoped asset lifecycle. Source URLs and object-store keys are server-side only and never appear in this response.
required: [id, organizationId, status, expiresAt, createdAt]
properties:
id: { type: string }
organizationId: { type: string }
taskId: { type: string, nullable: true }
sha256: { type: string, nullable: true, description: SHA-256 of the copied object; absent while pending or when legacy metadata is unavailable. }
sizeBytes: { type: integer, format: int64, minimum: 0, nullable: true, description: Verified byte size of the copied object; absent while pending. }
status: { type: string, enum: [pending, available, expired] }
expiresAt: { type: string, format: date-time }
createdAt: { type: string, format: date-time }
APIKeyScope:
type: string
enum: ['tasks:read', 'tasks:write', 'assets:read', 'assets:write', 'quotes:read', 'quotes:write', 'orders:read', 'orders:write', 'combinations:read', 'combinations:write', 'billing:read']
APIKeyRequest:
type: object
required: [name]
properties:
name: { type: string, minLength: 1, maxLength: 120, description: Single-line label measured in Unicode code points after trimming surrounding whitespace; control characters are rejected. }
scopes:
type: array
nullable: true
minItems: 1
maxItems: 11
description: Omitted/null defaults to read-only for all six resources. Writes must be explicitly selected. Unknown or administrative scopes are rejected.
items: { $ref: '#/components/schemas/APIKeyScope' }
APIKey:
type: object
required: [id, organizationId, name, prefix, last4, createdBy, scopes, legacy, principalActive, createdAt]
properties:
id: { type: string }
organizationId: { type: string }
name: { type: string }
prefix: { type: string }
last4: { type: string }
createdBy: { type: string }
scopes: { type: array, items: { $ref: '#/components/schemas/APIKeyScope' } }
legacy: { type: boolean, description: Migrated old key retains previous business scopes; never administrative or event-write scopes. }
principalActive: { type: boolean, description: Exact bound membership is currently active and verified. Unknown legacy creators remain inactive; admins may still list/revoke them. }
createdAt: { type: string, format: date-time }
lastUsedAt: { type: string, format: date-time, nullable: true, description: Last successful bearer authentication; absent means never used. }
revokedAt: { type: string, format: date-time, nullable: true }
TopUpRequest: { type: object, required: [account, amount, currency, operationId, approvalReference, approvedBy], properties: { account: { type: string, enum: [fiat, credits] }, amount: { type: integer, minimum: 1 }, currency: { type: string }, operationId: { type: string }, approvalReference: { type: string }, approvedBy: { type: string }, receiptReference: { type: string } } }
ExchangeRequest: { type: object, required: [fiatAmount, rateNumerator, rateDenominator, operationId, approvalReference, approvedBy, currency], properties: { fiatAmount: { type: integer, minimum: 1 }, rateNumerator: { type: integer, minimum: 1 }, rateDenominator: { type: integer, minimum: 1 }, operationId: { type: string }, approvalReference: { type: string }, approvedBy: { type: string }, currency: { type: string } } }
RefundRequest: { type: object, required: [sourceOperationId, refundOperationId, amount, reason], properties: { sourceOperationId: { type: string }, refundOperationId: { type: string }, amount: { type: integer, minimum: 1 }, reason: { type: string } } }
BalancePolicyRequest: { type: object, required: [approvalReference], properties: { minimumCredits: { type: integer, minimum: 0 }, minimumFiat: { type: integer, minimum: 0 }, creditLimitCredits: { type: integer, minimum: 0 }, creditLimitFiat: { type: integer, minimum: 0 }, postpayEnabled: { type: boolean }, approvalReference: { type: string } } }