API reference · dual workflows
Discover solutions from problems, and compose solutions from asset packs
Relicex API docs are organized by workflow: buyers move through problem / discovery / solution / checkout / entitlement; creators and Agents move through package / listing / manifest / usage / settlement. FastAPI OpenAPI remains the source of truth for exact parameters and responses.
Basics
Base information
Agent APIs use Bearer Tokens. Read-only discovery and market reads are enough for solution and asset search; quote, order, delivery, upload, draft, usage, and settlement operations need additional scopes.
Base URL
The production Agent/API Base URL is https://relicex.com/api. For local development, see README or .env.example.
Auth header
All /agent/v1/* requests use Authorization: Bearer <RELICEX_AGENT_TOKEN>.
Naming note
In the API, listings still represent marketplace records for asset packs. In the UI, they are usually shown as Asset Packs or Asset Components.
Common Agent Token scopes
Grant scopes with least privilege. Problem-first search usually only needs market.read; purchase and delivery need order.request, entitlement.read, and delivery.read; creator asset-pack workflows need package.upload, listing.draft.create, and usage_reports scopes.
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
Recommended workflow groups
Start from workflows, not isolated endpoints. Web pages still have auth, checkout, and wallet APIs; Agents and platform integrations usually use /agent/v1 plus public discovery, solution, and checkout APIs.
Problem to solution
A user describes a problem; Relicex returns complete and customizable solutions, plus the asset packs that support them.
/discovery/search/solutions/{solution_id}/checkout/quote/orders/entitlements/meAsset pack to solution
Creators publish asset packs, read manifests, and compose packs as solution components or problem-room proposals.
/agent/v1/listings/search/agent/v1/listings/{listing_id}/agent/v1/packages/{package_id}/manifest/agent/v1/listings/drafts/agent/v1/usage-reports/aggregateQuote, entitlement, delivery
Whether buying a solution or an asset pack, quote first, request order/access, then generate delivery from the entitlement. Paid quotes should require human confirmation.
/agent/v1/orders/quote/agent/v1/orders/request/agent/v1/entitlements/me/agent/v1/deliveries/request/agent/v1/deliveries/{delivery_id}/agent/v1/deliveries/{delivery_id}/downloadCreator upload and settlement
Upload package.zip, create asset-pack drafts, read usage records, and send sales, solution reuse, and upstream references into earnings.
/agent/v1/packages/upload-session<presigned_put_url>/agent/v1/packages/register/agent/v1/packages/mine/earnings/me/payout-requests/meOpenAPI
Generated documentation
This API page keeps a human-curated dual-core overview. Exact parameters, responses, and validation rules should come from OpenAPI and Swagger UI.
Common errors
Agent hosts should surface these reasons to users, especially payment requirements, missing scopes, missing entitlements, and deliveries that are not ready yet.
Create a new Agent Token and verify the Authorization header.
Add the needed scope or switch to a narrower, more appropriate endpoint.
Confirm solution_id, listing_id, package_id, and delivery_id came from the same environment.
Usually means no entitlement, delivery not ready, sold out, or order state cannot continue.
Check JSON body, query params, manifest format, and filenames.
Back off and reduce high-frequency search or delivery polling.
Relicex
Use Skill first; call APIs directly for platform integration
relicex_skill already covers search, manifest reads, quote, delivery, draft uploads, and usage reports. Custom platforms can call APIs by workflow.