{ "openapi": "3.1.0", "info": { "title": "Dosie Foxie Agent API", "version": "1.0.0", "summary": "A production brand pack from a structured brief, paid per pack with x402.", "description": "The agent checkout. Both the human Production Pack and the machine-callable x402 endpoints are live. Payment is USDC on Base (eip155:8453), exact scheme, verified and settled by a facilitator; the app holds no key. No account, API key or card is required. A request that arrives without payment returns 402 with the exact amount, asset, network and address, in the body and in a base64 PAYMENT-REQUIRED header. A successful order returns a manifest with signed URLs, a SHA-256 for every file, the palette, the font licence, the QA gate results and the parametric spec. A host with no treasury configured answers 503 with title `not_configured` rather than pretending to take money.", "contact": { "name": "Dosie Foxie", "email": "support@dosiefoxie.com", "url": "https://dosiefoxie.com/agents.html" }, "license": { "name": "Proprietary", "url": "https://dosiefoxie.com/terms.html" } }, "x-status": "live", "x-status-note": "GET /api/v1/pricing is authoritative for the current price and the payable address; agents should read it rather than hard-coding either.", "servers": [ { "url": "https://dosiefoxie.com/api/v1", "description": "Production" } ], "tags": [ { "name": "catalog", "description": "Free endpoints: sample pack and machine-readable pricing." }, { "name": "orders", "description": "Paid endpoints. The first request returns 402; the agent pays and retries." } ], "paths": { "/sample": { "get": { "tags": [ "catalog" ], "operationId": "getSample", "summary": "A real sample pack", "description": "Returns a signed URL to a real Production Pack built by the same engine, plus its manifest. No payment.", "responses": { "200": { "description": "Sample manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Manifest" } } } }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/pricing": { "get": { "tags": [ "catalog" ], "operationId": "getPricing", "summary": "Machine-readable prices and rails", "description": "Returns the current SKUs, prices, networks, assets and the preview status.", "responses": { "200": { "description": "Pricing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pricing" } } } } } } }, "/previews": { "post": { "tags": [ "orders" ], "operationId": "createPreview", "summary": "Three logo directions from a brief", "description": "Paid with x402: $1.00, credited toward a pack within 24 hours. Returns 202 with a preview id; poll GET /previews/{id}. The preview fee covers the model calls and filters spam.", "x-x402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000", "currency": "USDC", "decimals": 6 }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewRequest" } } } }, "responses": { "202": { "description": "Preview accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewAccepted" } } }, "headers": { "PAYMENT-RESPONSE": { "description": "Base64-encoded settlement response: the transaction hash and the network it settled on. Present when this call settled a payment.", "schema": { "type": "string" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "422": { "$ref": "#/components/responses/InvalidBrief" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The x402 authorization for this exact request: base64 JSON of an `exact` scheme payment. Omit it and the call answers 402 with the terms to sign; send the same request again with it and the payment is verified and settled. A signature is bound to the request body and the resource URL, so it cannot be replayed against another call." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "A client-generated key. Retrying with the same key and payment returns the original preview instead of drawing a second one." } ] } }, "/previews/{id}": { "get": { "tags": [ "orders" ], "operationId": "getPreview", "summary": "Preview status and concepts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preview" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/orders": { "post": { "tags": [ "orders" ], "operationId": "createOrder", "summary": "Buy a production pack", "description": "Paid with x402: $19.00 (founding $9.00 for the first 50 agents), less the $1.00 preview credit when the preview is under 24 hours old. Returns 202 with an order id; poll GET /orders/{id}. The chosen mark is traced once, the six gates run, and the pack is compiled. Polling is the supported callback; webhooks are not available yet.", "x-x402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "19000000", "currency": "USDC", "decimals": 6, "description": "The 402 is authoritative: $19, or $9 while the founding price lasts, less the $1 preview credit when the preview is under 24 hours old." }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "A client-generated key. Retrying with the same key and payment returns the original order." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The x402 authorization for this exact request: base64 JSON of an `exact` scheme payment. Omit it and the call answers 402 with the terms to sign; send the same request again with it and the payment is verified and settled. A signature is bound to the request body and the resource URL, so it cannot be replayed against another call." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequest" } } } }, "responses": { "202": { "description": "Order accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderAccepted" } } }, "headers": { "PAYMENT-RESPONSE": { "description": "Base64-encoded settlement response: the transaction hash and the network it settled on. Present when this call settled a payment.", "schema": { "type": "string" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/InvalidBrief" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/orders/{id}": { "get": { "tags": [ "orders" ], "operationId": "getOrder", "summary": "Order status and manifest", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/render": { "post": { "tags": [ "orders" ], "operationId": "renderSpec", "summary": "Re-render a pack from spec.json", "description": "Paid with x402: $1.00. No image model call; the pack is recompiled from the parametric spec. Use this for colour, layout, tagline, tracking and spacing changes. Re-render credits for a prior pack are roadmap, not implemented yet.", "x-x402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000", "currency": "USDC", "decimals": 6 }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Spec" } } } }, "responses": { "202": { "description": "Render accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderAccepted" } } }, "headers": { "PAYMENT-RESPONSE": { "description": "Base64-encoded settlement response: the transaction hash and the network it settled on. Present when this call settled a payment.", "schema": { "type": "string" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "422": { "$ref": "#/components/responses/InvalidBrief" } }, "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The x402 authorization for this exact request: base64 JSON of an `exact` scheme payment. Omit it and the call answers 402 with the terms to sign; send the same request again with it and the payment is verified and settled. A signature is bound to the request body and the resource URL, so it cannot be replayed against another call." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "A client-generated key. Retrying with the same key and payment returns the original order instead of building a second pack." } ] } }, "/keys": { "post": { "tags": [ "keys" ], "operationId": "createCredits", "summary": "Buy a prepaid balance, and get the key it mints", "description": "Paid with x402: 76.00 USDC buys a balance of 76.00 at face value - four preview-and-pack cycles at the published prices, with no invented discount, because the point of this SKU is the rail and not the price. The 202 carries the key once; a retry with the same Idempotency-Key returns the same key, because the server stores only its hash and derives the secret from the purchase. This is the payment rail an MCP client can use: a tool call has no headers to carry a PAYMENT-SIGNATURE, but it can carry a bearer token. Buying credits with credits is refused by construction - this path never reads Authorization.", "x-x402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "76000000", "currency": "USDC", "decimals": 6 }, "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The x402 authorization for this exact request: base64 JSON of an `exact` scheme payment. Omit it and the call answers 402 with the terms to sign; send the same request again with it and the payment is verified and settled. A signature is bound to the request body and the resource URL, so it cannot be replayed against another call." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "A client-generated key. Retrying with the same key and payment returns the original preview instead of drawing a second one." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsRequest" } } } }, "responses": { "202": { "description": "The balance was bought and the key minted", "headers": { "PAYMENT-RESPONSE": { "description": "Base64-encoded settlement response: the transaction hash and the network it settled on. Present when this call settled a payment.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsAccepted" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "422": { "description": "`email` is not an address." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "This host cannot mint a key: no seed is configured, so it refuses before taking money." } } }, "get": { "tags": [ "keys" ], "operationId": "getCredits", "summary": "The balance behind a key", "description": "Free, and only for the holder: present the key as `Authorization: Bearer `. A revoked or unknown key is 401, never a payment challenge.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The key's balance and the prices it will be charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyView" } } } }, "401": { "description": "No key, or not a key." } } } } }, "components": { "responses": { "PaymentRequired": { "description": "Payment required. The PAYMENT-REQUIRED header carries the base64-encoded payment requirements.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded x402 PaymentRequired object.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "InvalidBrief": { "description": "The brief is missing required fields or asks for something the engine cannot deliver.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "RateLimited": { "description": "Too many requests. Retry after the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Conflict": { "description": "The idempotency key was reused with a different request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "No such preview or order.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unavailable": { "description": "The service is temporarily unavailable. Retry after the Retry-After header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "Brief": { "type": "object", "required": [ "name", "trade" ], "properties": { "name": { "type": "string", "maxLength": 40, "description": "The trading name, typeset by the engine. Never rendered by the image model." }, "trade": { "type": "string", "maxLength": 80, "description": "What the business does. The strongest quality lever." }, "audience": { "type": "string", "maxLength": 160 }, "style": { "type": "string", "enum": [ "auto", "mascot", "badge", "monoline", "woodcut", "geometric", "abstract", "retro", "illustration", "monogram", "emblem" ], "description": "The register the mark is drawn in. `auto` lets the designer choose. `monogram` and `emblem` are composed by the engine rather than drawn, and are the only two that need nothing from the image model. Keys are the ones app/style.py implements." }, "must_include": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 4 }, "avoid": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 6 }, "tagline": { "type": "string", "maxLength": 80 }, "notes": { "type": "string", "maxLength": 600 } }, "additionalProperties": false }, "PreviewRequest": { "type": "object", "required": [ "brief" ], "properties": { "brief": { "$ref": "#/components/schemas/Brief" } }, "additionalProperties": false }, "PreviewAccepted": { "type": "object", "required": [ "preview_id", "status_url", "estimated_seconds" ], "properties": { "preview_id": { "type": "string" }, "status_url": { "type": "string", "format": "uri" }, "estimated_seconds": { "type": "integer", "minimum": 30 }, "expires_at": { "type": "string", "format": "date-time" } } }, "Concept": { "type": "object", "required": [ "id", "png_url", "qa" ], "properties": { "id": { "type": "string" }, "concept": { "type": "string" }, "png_url": { "type": "string", "format": "uri" }, "svg_url": { "type": "string", "format": "uri" }, "qa": { "$ref": "#/components/schemas/QA" } } }, "Preview": { "type": "object", "required": [ "preview_id", "status", "concepts" ], "properties": { "preview_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "drawing", "ready", "failed", "expired" ] }, "concepts": { "type": "array", "items": { "$ref": "#/components/schemas/Concept" } }, "error": { "$ref": "#/components/schemas/Problem" } } }, "OrderRequest": { "type": "object", "required": [ "preview_id", "concept_id" ], "properties": { "preview_id": { "type": "string" }, "concept_id": { "type": "string" } }, "additionalProperties": false, "description": "The preview_id and the chosen concept_id. Poll the status_url; webhooks and add-ons are not available yet." }, "OrderAccepted": { "type": "object", "required": [ "order_id", "status_url", "estimated_seconds" ], "properties": { "order_id": { "type": "string" }, "status_url": { "type": "string", "format": "uri" }, "estimated_seconds": { "type": "integer", "minimum": 5 } } }, "Order": { "type": "object", "required": [ "order_id", "status" ], "properties": { "order_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "producing", "delivered", "refunded", "failed" ] }, "manifest": { "$ref": "#/components/schemas/Manifest" }, "error": { "$ref": "#/components/schemas/Problem" }, "refund": { "$ref": "#/components/schemas/Refund" } } }, "Manifest": { "type": "object", "required": [ "order_id", "files", "qa", "license" ], "properties": { "order_id": { "type": "string" }, "spec_url": { "type": "string", "format": "uri" }, "mark_svg_url": { "type": "string", "format": "uri" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/File" } }, "palette": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "hex": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } } } }, "fonts": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "license": { "type": "string" } } } }, "qa": { "$ref": "#/components/schemas/QA" }, "license": { "type": "object", "properties": { "owner": { "type": "string" }, "terms_url": { "type": "string", "format": "uri" } } }, "expires_at": { "type": "string", "format": "date-time" }, "download_url": { "type": "string", "format": "uri" }, "price_paid_micros": { "type": "integer", "description": "Atomic USDC units actually paid, after the preview credit." } } }, "File": { "type": "object", "required": [ "name", "kind", "use", "bytes", "sha256" ], "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "vector", "raster", "icon", "document" ] }, "use": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "QA": { "type": "object", "required": [ "passed", "gates" ], "properties": { "passed": { "type": "boolean" }, "gates": { "type": "array", "items": { "type": "string" } }, "details": { "type": "object", "additionalProperties": true } } }, "Spec": { "type": "object", "required": [ "name", "layout", "mark", "type", "palette" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "\\S" }, "layout": { "type": "string", "enum": [ "horizontal", "stacked", "wordmark", "icon" ] }, "mark": { "type": "object", "required": [ "family" ], "additionalProperties": true, "properties": { "family": { "type": "string", "enum": [ "monogram", "emblem", "petals", "rings", "stack" ], "description": "`custom` is refused: it needs an uploaded SVG, which this endpoint does not accept." }, "letters": { "type": "string", "minLength": 1, "maxLength": 4, "description": "Required when `family` is `monogram`, ignored otherwise." }, "symbol": { "type": "string", "enum": [ "drop", "leaf", "bolt", "cup", "roof", "wave", "wheel", "plus", "spark" ], "description": "Required when `family` is `emblem`, ignored otherwise." }, "count": { "type": "integer", "minimum": 3, "maximum": 12, "description": "Required for `petals` and `rings` (3-12). Optional for `stack`, where it is 3-6." }, "scale": { "type": "number", "minimum": 0.8, "maximum": 2.6 }, "gap": { "type": "number", "minimum": 0.08, "maximum": 0.9 } }, "allOf": [ { "if": { "properties": { "family": { "const": "monogram" } }, "required": [ "family" ] }, "then": { "required": [ "letters" ] } }, { "if": { "properties": { "family": { "const": "emblem" } }, "required": [ "family" ] }, "then": { "required": [ "symbol" ] } }, { "if": { "properties": { "family": { "const": "stack" } }, "required": [ "family" ] }, "then": { "properties": { "count": { "minimum": 3, "maximum": 6 } } } }, { "if": { "properties": { "family": { "enum": [ "petals", "rings" ] } }, "required": [ "family" ] }, "then": { "required": [ "count" ] } } ] }, "type": { "type": "object", "required": [ "font" ], "additionalProperties": true, "properties": { "font": { "type": "string", "enum": [ "Anton", "AlfaSlabOne", "BebasNeue", "DMSerifDisplay", "Inter-Bold", "Inter-Medium" ] }, "tracking": { "type": "number", "minimum": -0.05, "maximum": 0.3 } } }, "palette": { "type": "object", "required": [ "primary", "accent", "paper" ], "additionalProperties": true, "properties": { "primary": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "paper": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } } }, "tagline": { "type": "string", "maxLength": 40, "description": "Refused, not ignored, on `layout: icon`: the icon composition has nowhere to put the line." } }, "additionalProperties": true, "allOf": [ { "if": { "properties": { "layout": { "const": "icon" } }, "required": [ "layout" ] }, "then": { "properties": { "tagline": { "maxLength": 0 } } } } ] }, "Pricing": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "preview": { "type": "integer", "description": "Atomic USDC units (6 decimals)." }, "pack": { "type": "integer" }, "pro": { "type": "integer" }, "render": { "type": "integer" }, "networks": { "type": "array", "items": { "type": "string" } }, "asset": { "type": "string" }, "pay_to": { "type": "string" }, "status": { "type": "string", "enum": [ "preview", "live" ] }, "decimals": { "type": "integer", "enum": [ 6 ] }, "preview_credit": { "type": "boolean" }, "founding": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "price": { "type": "integer" }, "limit": { "type": "integer" }, "remaining": { "type": "integer" } } } } }, "PaymentRequired": { "type": "object", "required": [ "x402Version", "accepts" ], "properties": { "x402Version": { "type": "integer", "enum": [ 2 ] }, "resource": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "mimeType": { "type": "string" } } }, "accepts": { "type": "array", "items": { "type": "object", "required": [ "scheme", "network", "amount", "asset", "payTo" ], "properties": { "scheme": { "type": "string", "enum": [ "exact" ] }, "network": { "type": "string" }, "amount": { "type": "string" }, "asset": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer" }, "extra": { "type": "object", "additionalProperties": true } } } }, "extensions": { "type": "object", "additionalProperties": true }, "error": { "type": "string" }, "errorMessage": { "type": "string" } } }, "Problem": { "type": "object", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "next_action": { "type": "string" }, "missing": { "type": "array", "items": { "type": "string" } }, "suggested_brief": { "$ref": "#/components/schemas/Brief" } } }, "Refund": { "type": "object", "description": "What the buyer is owed after a pack could not be built. `pending` means the operator has been alerted and the USDC has not moved; `sent` means it is on-chain and `tx_hash` verifies it on Base; `credited` is the prepaid-key rail, where the money never left the balance and was put back, so there is no transaction. A preview is never refunded in cash - its fee is credited toward a retry.", "required": [ "status", "amount_micros" ], "properties": { "status": { "type": "string", "enum": [ "pending", "sent", "credited" ] }, "amount_micros": { "type": "integer", "description": "atomic USDC units (1e-6)" }, "tx_hash": { "type": [ "string", "null" ], "description": "the Base transaction that returned the money; null while pending" } } }, "CreditsRequest": { "type": "object", "description": "The body is optional. An email is only used to label the key.", "properties": { "email": { "type": "string", "format": "email", "description": "Where to reach the buyer about this balance. Omitted, the key is labelled as an agent's." } } }, "CreditsAccepted": { "type": "object", "required": [ "key", "key_id", "balance_micros" ], "properties": { "key": { "type": "string", "description": "The secret, `foxie_sk_...`. Sent once per response; the database holds only its hash, and the server derives it again from the purchase." }, "key_id": { "type": "string" }, "prefix": { "type": "string", "description": "Enough of the key for support to find it." }, "balance_micros": { "type": "integer", "description": "atomic USDC units (1e-6)" }, "rail": { "type": "string", "enum": [ "credits" ] }, "use": { "type": "string", "description": "The header to present the key in." }, "note": { "type": "string" } } }, "KeyView": { "type": "object", "required": [ "key_id", "balance_micros" ], "properties": { "key_id": { "type": "string" }, "prefix": { "type": "string" }, "balance_micros": { "type": "integer" }, "email": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "pricing": { "type": "object", "description": "The prices this balance will be charged, in atomic USDC units.", "properties": { "preview_micros": { "type": "integer" }, "pack_micros": { "type": "integer" }, "render_micros": { "type": "integer" } } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A prepaid key, `foxie_sk_...`. Buy one at POST /keys, or ask support for an invoiced balance." } } } }