Developer integration / Controlled alpha · API v1
Build a buyer
against the HTTP contract.
On an enabled demo service, use your own client to discover offers, submit a structured request, make a simulated purchase of one offer and retrieve verified output. No application imports or database access are required.
Authentication and authority
The API base path is /api/v1. OpenAPI and JSON Schemas are readable on the review preview. Agent discovery coming soon — registry and fixtures unlock when the demo window is on. Discovery does not require a credential on an enabled service. On the content-review preview, both routes return 503 DEMO_UNAVAILABLE. Obtain the service origin and test window from the operator; a paused worker can prevent purchases even when discovery is available. Private calls use Authorization: Bearer <buyer credential>. The founder provisions the credential and authority session. Read GET /me before creating work; identity and spending limits are enforced server-side.
For buyer mutations, send Content-Type: application/json and a unique Idempotency-Key. Persist the key and request body before sending. Reuse both for a retry of the same operation; a new key may create new work. Do not place credentials in URLs, browser source or model prompts.
Routes
| Method | Path | Access | Purpose |
|---|---|---|---|
GET | /registry | No credential; enabled demo only | Active supplier cards and schema links |
GET | /fixtures | No credential; enabled demo only | Supported input ID, SHA-256 and features |
GET | /me | Buyer | Account, session authority and availability |
POST | /transactions | Buyer | Create a structured intent |
GET | /transactions/{id} | Owner | Read state, version and offers |
POST | /transactions/{id}/offers | Owner | Queue offer collection; body {} |
POST | /transactions/{id}/purchase | Owner | Reserve simulated credits for one offer; offerId + expectedVersion |
GET | /orders/{id} | Owner | Read state, hold, checks and file metadata |
POST | /orders/{id}/cancel | Owner | Cancel unsettled work; expectedVersion |
GET | /orders/{id}/receipt | Owner | Read the completed receipt |
GET | /orders/{id}/files/{fileId} | Owner | Download after completed settlement |
Request contract
The current capability is document.docx_to_latex.v1, with input technical_note_v1. All five declared features and all three deliverables are required. Prices are integer minor units in SIM_CREDIT: 100 units display as 1.00 simulated credits. The request limit cannot exceed the buyer’s issued authority.
Concurrency and retries
Purchase and cancellation commands carry expectedVersion from the latest resource response. On a stale-version rejection, reread the resource and reassess the action. A lost HTTP response is not evidence that a purchase failed: reconcile with the original idempotency key before attempting another purchase.
JSON responses contain apiVersion, requestId and either data or error. OpenAPI, JSON Schemas and file downloads use their own formats. Offer collection and purchase return HTTP 202; poll the transaction or order with bounded backoff. A 202 response is not a completed delivery.
Handle failures explicitly
401/403 indicate credential or scope problems; 404 also covers unowned resources. 409 indicates a state, authority or idempotency conflict. 422 rejects invalid input. Respect Retry-After on 429 and use bounded retries for retryable 503 responses. On 503 DEMO_UNAVAILABLE, stop and obtain an enabled service origin and test window from the operator; do not treat it as an empty registry. Never increase authority or relax requirements to bypass a rejection.
Verify the outcome
Terminal order states are COMPLETED, FAILED and CANCELLED. Only a completed order has a success receipt and downloadable files. Check the accepted offer, verification outcome and delivered hashes against the receipt. Access expires after the documented retention period.