Relicex
登录立即开始

API 参考 · 双工作流

从问题发现方案，也从资产包组合方案

Relicex API 参考按 workflow 组织：买家从 problem / discovery / solution / checkout / entitlement 进入；创作者和 Agent 从 package / listing / manifest / usage / settlement 进入。FastAPI OpenAPI schema 仍然是参数和响应结构的最终来源。

打开 Swagger UI查看示例代码
Problem → SolutionAsset Pack → SolutionEntitlement → Settlement

Basics

基础信息

Agent API 使用 Bearer Token。只读 discovery / market read 适合搜索方案和资产包；quote、order、delivery、upload、draft、usage 和 settlement 需要按需打开 scope。

Base URL

线上 Agent/API Base URL 为 https://relicex.com/api。开发环境请参考本地 README 或 .env.example 配置。

认证 Header

所有 /agent/v1/* 请求使用 Authorization: Bearer <RELICEX_AGENT_TOKEN>。

命名说明

API 中 listing 仍代表资产包的市场记录；产品界面通常展示为 Asset Pack / Asset Component。

常用 Agent Token scope

按最小权限原则给 Agent 分配 scope。problem-first 搜索通常只需要 market.read；购买和交付需要 order.request、entitlement.read、delivery.read；创作者资产包工作流需要 package.upload、listing.draft.create 和 usage_reports 权限。

market.readpackage.manifest.readentitlement.readorder.requestdelivery.readpackage.uploadlisting.draft.createusage_reports:readusage_reports:writesecret.runtime.resolveaudit.read
请求通用格式
RELICEX_API_BASE_URL="https://relicex.com/api"
Authorization: Bearer <RELICEX_AGENT_TOKEN>
Content-Type: application/json
# Commercial tasks must use license_scope=commercial.
# Subscription access uses access_mode=subscription.

Workflows

推荐 workflow 组

优先从工作流理解接口。Web 页面仍有自己的 auth、checkout、wallet 等接口；Agent 和平台集成通常使用 /agent/v1 和公开 discovery / solution / checkout API。

Problem to solution

用户描述问题，系统返回 complete / customizable solutions，并展示支撑它们的资产包。

POST/discovery/search
GET/solutions/{solution_id}
POST/checkout/quote
POST/orders
GET/entitlements/me

Asset pack to solution

创作者发布资产包，读取 manifest，再把资产包作为组件组合进方案或提交到 problem room。

GET/agent/v1/listings/search
GET/agent/v1/listings/{listing_id}
GET/agent/v1/packages/{package_id}/manifest
POST/agent/v1/listings/drafts
GET/agent/v1/usage-reports/aggregate

Quote, entitlement, delivery

无论购买方案还是资产包，都先 quote，再请求订单/授权，并按 entitlement 生成 delivery。付费 quote 前应有人确认。

POST/agent/v1/orders/quote
POST/agent/v1/orders/request
GET/agent/v1/entitlements/me
POST/agent/v1/deliveries/request
GET/agent/v1/deliveries/{delivery_id}
GET/agent/v1/deliveries/{delivery_id}/download

Creator upload and settlement

上传 package.zip、创建资产包草稿、读取使用记录，并把销售、方案复用和上游引用进入收益后台。

POST/agent/v1/packages/upload-session
PUT<presigned_put_url>
POST/agent/v1/packages/register
GET/agent/v1/packages/mine
GET/earnings/me
GET/payout-requests/me

OpenAPI

自动文档入口

API 参考页只保留人工整理的双核心路径。接口参数、响应结构和校验规则以 OpenAPI 和 Swagger UI 为准。

打开 Swagger UI

https://relicex.com/api/docs

查看 openapi.json

https://relicex.com/api/openapi.json

创建 Agent Token

Agent Token

Manifest 规范

manifest.json 是资产包技术合同；方案复用前也应理解它。

常见错误码

Agent 宿主应该把错误原因展示给用户，尤其是支付需求、scope 不足、授权缺失和交付尚未 ready 的情况。

401Token 无效或缺失

重新生成 Agent Token，确认 Authorization Header。

403scope 不足

给 token 补充对应 scope，或换用权限更窄/更合适的接口。

404资源不存在

确认 solution_id、listing_id、package_id、delivery_id 是否来自当前环境。

409状态冲突

常见于未授权、交付尚未 ready、已售罄、订单状态不可继续等场景。

422参数错误

检查 JSON body、query 参数、manifest 格式和文件名。

429速率限制

退避重试，并减少高频搜索或下载轮询。

Relicex

先用 Skill，平台集成再直接调 API

relicex_skill 已覆盖搜索、manifest、quote、交付、上传草稿和 usage report。自定义平台再按 workflow 调用 API。

查看示例代码连接 AI