{ "openapi": "3.1.0", "info": { "title": "Api", "version": "0.0.1" }, "paths": { "/api/v1/credits": { "get": { "tags": [ "billing" ], "operationId": "billing.getCredits", "parameters": [], "security": [], "responses": { "200": { "description": "GET /credits response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "userId", "balance" ], "properties": { "userId": { "type": "string", "description": "Identifier of the authenticated user account", "title": "maxLength(80)", "minLength": 3, "maxLength": 80 }, "balance": { "type": "integer", "description": "Current spendable credit balance", "title": "int" } }, "additionalProperties": false, "description": "GET /credits response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/billing/pricing": { "get": { "tags": [ "billing" ], "operationId": "billing.getPricing", "parameters": [], "security": [], "responses": { "200": { "description": "GET /billing/pricing response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "configured", "source", "storeUrl", "currency", "packs", "updatedAt" ], "properties": { "configured": { "type": "boolean", "description": "Whether the billing catalog is configured for purchases" }, "source": { "type": "string", "enum": [ "lemon_squeezy" ], "description": "Merchant-of-record source for the pricing catalog" }, "storeUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Public Lemon Squeezy storefront URL, or null when unavailable" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Shared ISO currency code for the catalog, or null when mixed or empty" }, "packs": { "type": "array", "items": { "type": "object", "required": [ "packId", "variantId", "name", "description", "priceCents", "currency", "priceFormatted", "status", "statusFormatted", "testMode", "buyNowUrl", "sort" ], "properties": { "packId": { "type": "string", "enum": [ "image_credits_12", "image_credits_30", "image_credits_60", "image_credits_custom" ], "description": "Stable genshot credit-pack identifier" }, "variantId": { "type": "string", "description": "Lemon Squeezy variant identifier backing the pack" }, "name": { "type": "string", "description": "Public display name of the credit pack" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Public pack description, or null when none is configured" }, "priceCents": { "type": "integer", "description": "Pack price in the smallest currency unit", "title": "int" }, "currency": { "type": "string", "description": "ISO currency code for the pack price" }, "priceFormatted": { "type": "string", "description": "Human-formatted pack price including its currency" }, "status": { "type": "string", "description": "Machine-readable availability state" }, "statusFormatted": { "type": "string", "description": "Human-readable availability state" }, "testMode": { "type": "boolean", "description": "Whether the backing Lemon Squeezy variant is in test mode" }, "buyNowUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Hosted direct-purchase URL, or null when unavailable" }, "sort": { "type": "integer", "description": "Ascending display order for the pack", "title": "int" } }, "additionalProperties": false, "description": "Public pricing details for one purchasable credit pack" }, "description": "Purchasable credit packs in display order" }, "centsPerCredit": { "allOf": [ { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "greaterThan(0)", "exclusiveMinimum": 0 } ], "description": "List price in USD cents for one credit / one successful image from D1 runtime state (ADR-0028)" }, "pwywMinCents": { "allOf": [ { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "greaterThan(0)", "exclusiveMinimum": 0 } ], "description": "Recommended Lemon PWYW minimum in cents (max of platform floor and one credit list price)" }, "costMultiplier": { "type": "number", "description": "ADR-0026 measured-cost to list multiplier applied when remeasuring packs", "title": "greaterThan(0)", "exclusiveMinimum": 0 }, "pricingSource": { "type": "string", "enum": [ "seed", "d1_remeasure", "manual", "unknown" ], "description": "How the current centsPerCredit was last set (seed, remeasure, or manual)" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the pricing response was assembled" } }, "additionalProperties": false, "description": "GET /billing/pricing response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/billing/checkout": { "post": { "tags": [ "billing" ], "operationId": "billing.createCheckout", "parameters": [], "security": [], "responses": { "200": { "description": "POST /billing/checkout response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "checkoutUrl", "credits", "amountCents" ], "properties": { "checkoutUrl": { "type": "string", "description": "Hosted checkout URL for the selected credit pack" }, "credits": { "$ref": "#/components/schemas/Int", "description": "Number of image credits purchased by the checkout", "title": "greaterThan(0)", "exclusiveMinimum": 0 }, "amountCents": { "$ref": "#/components/schemas/Int", "description": "Checkout price in the smallest currency unit", "title": "greaterThan(0)", "exclusiveMinimum": 0 } }, "additionalProperties": false, "description": "POST /billing/checkout response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/dashboard/billing/checkout": { "post": { "tags": [ "billing" ], "operationId": "billing.createDashboardCheckout", "parameters": [], "security": [], "responses": { "200": { "description": "POST /billing/checkout response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "checkoutUrl", "credits", "amountCents" ], "properties": { "checkoutUrl": { "type": "string", "description": "Hosted checkout URL for the selected credit pack" }, "credits": { "$ref": "#/components/schemas/Int", "description": "Number of image credits purchased by the checkout", "title": "greaterThan(0)", "exclusiveMinimum": 0 }, "amountCents": { "$ref": "#/components/schemas/Int", "description": "Checkout price in the smallest currency unit", "title": "greaterThan(0)", "exclusiveMinimum": 0 } }, "additionalProperties": false, "description": "POST /billing/checkout response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/dashboard/billing/overview": { "get": { "tags": [ "billing" ], "operationId": "billing.getDashboardBillingOverview", "parameters": [], "security": [], "responses": { "200": { "description": "GET /dashboard/billing/overview response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "creditsRemaining", "lemonCustomerId", "invoices", "ledger" ], "properties": { "creditsRemaining": { "type": "integer", "description": "Current spendable credit balance", "title": "int" }, "lemonCustomerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Linked Lemon customer id when known" }, "invoices": { "type": "array", "items": { "type": "object", "required": [ "id", "lemonOrderId", "amountCents", "currency", "creditsGranted", "status", "createdAt", "receiptUrl", "productName", "source" ], "properties": { "id": { "type": "string", "description": "Stable invoice row id (Lemon order id or local purchase id)" }, "lemonOrderId": { "type": "string", "description": "Lemon Squeezy order identifier" }, "amountCents": { "type": "integer", "description": "Order total in the smallest currency unit", "title": "int" }, "currency": { "type": "string", "description": "ISO currency code for the order total" }, "creditsGranted": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ], "description": "Credits granted for this order in genshot, or null when not yet applied" }, "status": { "type": "string", "description": "Human-readable status (paid, refunded, applied, …)" }, "createdAt": { "type": "string", "description": "ISO timestamp when the order was created" }, "receiptUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lemon customer receipt URL, or null when unavailable" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lemon product / first order item name when known" }, "source": { "type": "string", "enum": [ "lemon_squeezy", "local" ], "description": "Whether the row was hydrated from the Lemon API or local purchase ledger only" } }, "additionalProperties": false, "description": "One billing invoice / purchase row for the dashboard" }, "description": "Orders / invoices newest first (Lemon when available, else local purchases)" }, "ledger": { "type": "array", "items": { "type": "object", "required": [ "id", "type", "amount", "balanceAfter", "note", "createdAt" ], "properties": { "id": { "type": "string", "description": "Credit ledger row id" }, "type": { "type": "string", "description": "Ledger entry type (purchase, reservation, beta_grant, …)" }, "amount": { "type": "integer", "description": "Signed credit delta (positive grant, negative spend/reserve)", "title": "int" }, "balanceAfter": { "type": "integer", "description": "Spendable balance after this entry", "title": "int" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional human note" }, "createdAt": { "type": "string", "description": "ISO timestamp when the entry was written" } }, "additionalProperties": false, "description": "One credit ledger activity row" }, "description": "Recent credit ledger entries newest first" } }, "additionalProperties": false, "description": "GET /dashboard/billing/overview response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/admin/billing/pricing-state": { "get": { "tags": [ "billing" ], "operationId": "billing.getBillingPricingState", "parameters": [], "security": [], "responses": { "200": { "description": "GET /admin/billing/pricing-state response", "content": { "application/json": { "schema": { "type": "object", "required": [ "centsPerCredit", "measuredAvgCostCents", "sampleCount", "source", "updatedAt", "pwywMinCents", "costMultiplier", "note", "packTargets" ], "properties": { "centsPerCredit": { "$ref": "#/components/schemas/Int", "description": "Runtime list cents per credit", "title": "greaterThan(0)", "exclusiveMinimum": 0 }, "measuredAvgCostCents": { "anyOf": [ { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "greaterThanOrEqualTo(0)", "minimum": 0 }, { "type": "null" } ], "description": "Last measured avg cost in cents" }, "sampleCount": { "$ref": "#/components/schemas/Int", "description": "Samples behind the last remeasure", "title": "greaterThanOrEqualTo(0)", "minimum": 0 }, "source": { "type": "string", "description": "seed | d1_remeasure | manual" }, "updatedAt": { "type": "string", "description": "ISO timestamp of last write" }, "pwywMinCents": { "$ref": "#/components/schemas/Int", "description": "Recommended PWYW minimum cents", "title": "greaterThan(0)", "exclusiveMinimum": 0 }, "costMultiplier": { "type": "number", "description": "ADR-0026 multiplier (1.5)" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last remeasure note" }, "packTargets": { "type": "array", "items": { "type": "object", "required": [ "packId", "credits", "targetAmountCents" ], "properties": { "packId": { "type": "string", "description": "Credit pack id" }, "credits": { "type": "integer", "description": "Images in the pack", "title": "int" }, "targetAmountCents": { "type": "integer", "description": "credits × centsPerCredit catalog target", "title": "int" } }, "additionalProperties": false }, "description": "Fixed + custom suggested list amounts at runtime cents" } }, "additionalProperties": false, "description": "GET /admin/billing/pricing-state response" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/admin/billing/remeasure": { "post": { "tags": [ "billing" ], "operationId": "billing.remeasureBillingPricing", "parameters": [], "security": [], "responses": { "200": { "description": "POST /admin/billing/remeasure response", "content": { "application/json": { "schema": { "type": "object", "required": [ "applied", "dryRun", "action", "reason", "previousCentsPerCredit", "nextCentsPerCredit", "measuredAvgCostCents", "samples", "deltaCents", "pwywMinCents", "lemonSyncNote" ], "properties": { "applied": { "type": "boolean", "description": "Whether D1 was written" }, "dryRun": { "type": "boolean", "description": "Whether this was a dry run" }, "action": { "type": "string", "enum": [ "apply", "skip" ], "description": "Remeasure decision action" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Skip reason when action is skip" }, "previousCentsPerCredit": { "type": "integer", "description": "Cents before decision", "title": "int" }, "nextCentsPerCredit": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ], "description": "Proposed or applied list cents" }, "measuredAvgCostCents": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ], "description": "Rounded avg cost cents from samples" }, "samples": { "type": "integer", "description": "Succeeded cost samples used", "title": "int" }, "deltaCents": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ], "description": "Absolute list-cent delta" }, "pwywMinCents": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ], "description": "Recommended PWYW min after next cents" }, "lemonSyncNote": { "type": "string", "description": "Operator reminder to sync Lemon catalog when applied" }, "state": { "type": "object", "required": [ "centsPerCredit", "measuredAvgCostCents", "sampleCount", "source", "updatedAt", "pwywMinCents", "costMultiplier", "note", "packTargets" ], "properties": { "centsPerCredit": { "$ref": "#/components/schemas/Int", "description": "Runtime list cents per credit", "title": "greaterThan(0)", "exclusiveMinimum": 0 }, "measuredAvgCostCents": { "anyOf": [ { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "greaterThanOrEqualTo(0)", "minimum": 0 }, { "type": "null" } ], "description": "Last measured avg cost in cents" }, "sampleCount": { "$ref": "#/components/schemas/Int", "description": "Samples behind the last remeasure", "title": "greaterThanOrEqualTo(0)", "minimum": 0 }, "source": { "type": "string", "description": "seed | d1_remeasure | manual" }, "updatedAt": { "type": "string", "description": "ISO timestamp of last write" }, "pwywMinCents": { "$ref": "#/components/schemas/Int", "description": "Recommended PWYW minimum cents", "title": "greaterThan(0)", "exclusiveMinimum": 0 }, "costMultiplier": { "type": "number", "description": "ADR-0026 multiplier (1.5)" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last remeasure note" }, "packTargets": { "type": "array", "items": { "type": "object", "required": [ "packId", "credits", "targetAmountCents" ], "properties": { "packId": { "type": "string", "description": "Credit pack id" }, "credits": { "type": "integer", "description": "Images in the pack", "title": "int" }, "targetAmountCents": { "type": "integer", "description": "credits × centsPerCredit catalog target", "title": "int" } }, "additionalProperties": false }, "description": "Fixed + custom suggested list amounts at runtime cents" } }, "additionalProperties": false, "description": "Updated state when applied (or current on skip/dry-run)" } }, "additionalProperties": false, "description": "POST /admin/billing/remeasure response" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/webhooks/lemon-squeezy": { "post": { "tags": [ "billing" ], "operationId": "billing.handleLemonWebhook", "parameters": [], "security": [], "responses": { "200": { "description": "Applied Lemon Squeezy webhook result with the purchase id", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "applied", "purchaseId" ], "properties": { "applied": { "type": "boolean", "enum": [ true ], "description": "True when the order-created event granted credits" }, "purchaseId": { "type": "string", "description": "Idempotent purchase row id created for the granted order" } }, "additionalProperties": false, "description": "Applied Lemon Squeezy webhook result with the purchase id" }, { "type": "object", "required": [ "applied", "reason" ], "properties": { "applied": { "type": "boolean", "enum": [ false ], "description": "False when the webhook event was intentionally not applied" }, "reason": { "type": "string", "enum": [ "duplicate_order", "ignored_event", "ignored_variant", "ignored_zero_credits" ], "description": "Machine-readable reason the webhook event was skipped" } }, "additionalProperties": false, "description": "Skipped Lemon Squeezy webhook result with the ignore reason" } ] } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/generations": { "post": { "tags": [ "generation" ], "operationId": "generation.createGeneration", "parameters": [], "security": [], "responses": { "200": { "description": "POST /generations acknowledgement body", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "status" ], "properties": { "jobId": { "type": "string", "description": "Queued or replayed generation job id", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "status": { "type": "string", "description": "Job lifecycle status at acknowledge time (usually queued)", "title": "minLength(1)", "minLength": 1 }, "idempotentReplay": { "type": "boolean", "description": "True when an existing job was returned for the same Idempotency-Key" } }, "additionalProperties": false, "description": "POST /generations acknowledgement body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "request": { "type": "object", "required": [ "version", "marketplace", "sourceUrl", "count", "prompt" ], "properties": { "version": { "type": "number", "enum": [ 1 ], "description": "Generation request schema version." }, "marketplace": { "type": "string", "enum": [ "app_store", "chrome_web_store", "google_play" ], "description": "Storefront that receives a generated asset set." }, "sourceUrl": { "type": "string", "description": "Public listing URL for the selected marketplace.", "title": "minLength(1)", "minLength": 1 }, "count": { "$ref": "#/components/schemas/Int", "description": "Number of generated assets requested.", "title": "between(1, 10)", "minimum": 1, "maximum": 10 }, "prompt": { "type": "string", "description": "Art-direction prompt for the generated asset set.", "title": "minLength(1)", "minLength": 1 } }, "additionalProperties": false, "description": "Versioned public marketplace generation request." }, "appStoreUrl": { "type": "string" }, "count": { "allOf": [ { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 10", "title": "between(1, 10)", "minimum": 1, "maximum": 10 } ], "description": "Number of panels to generate, defaulting to four" }, "uploadedAssetIds": { "type": "array", "items": { "type": "string", "description": "a string at most 80 character(s) long", "title": "maxLength(80)", "minLength": 3, "maxLength": 80 }, "description": "an array of at most 10 item(s)", "title": "maxItems(10)", "maxItems": 10 }, "prompt": { "type": "string", "description": "Art-direction prompt for the set", "title": "minLength(1)", "minLength": 1 } }, "additionalProperties": false } } }, "required": true } } }, "/api/v1/generations/{jobId}": { "get": { "tags": [ "generation" ], "operationId": "generation.getGenerationStatus", "parameters": [ { "name": "jobId", "in": "path", "schema": { "type": "string", "description": "Generation job id from the route path" }, "required": true, "description": "Generation job id from the route path" } ], "security": [], "responses": { "200": { "description": "GET /generations/:id response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "status", "requestedCount", "succeededCount", "failedCount", "creditsReserved", "creditsSpent", "creditsReleased", "outputs", "error", "createdAt", "updatedAt", "deletedAt" ], "properties": { "jobId": { "type": "string", "description": "Generation job id", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "status": { "type": "string", "enum": [ "queued", "processing", "succeeded", "failed", "deleted" ], "description": "Lifecycle status of the job" }, "requestedCount": { "type": "integer", "description": "Panels requested", "title": "int" }, "succeededCount": { "type": "integer", "description": "Panels that succeeded", "title": "int" }, "failedCount": { "type": "integer", "description": "Panels that failed", "title": "int" }, "creditsReserved": { "type": "integer", "description": "Credits held for this job", "title": "int" }, "creditsSpent": { "type": "integer", "description": "Credits charged for successes", "title": "int" }, "creditsReleased": { "type": "integer", "description": "Credits released on failure", "title": "int" }, "outputs": { "type": "array", "items": { "type": "object", "required": [ "id", "index", "status", "url", "expiresAt" ], "properties": { "id": { "type": "string", "description": "Identifier of the generated output asset", "title": "maxLength(80)", "minLength": 3, "maxLength": 80 }, "index": { "$ref": "#/components/schemas/Int", "description": "Zero-based panel index in the set", "title": "greaterThanOrEqualTo(0)", "minimum": 0 }, "status": { "type": "string", "enum": [ "succeeded", "failed", "deleted" ], "description": "Terminal status of this output" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Signed download URL, or null when unavailable" }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO expiry of the signed URL, or null" } }, "additionalProperties": false, "description": "One generated image on a generation job" }, "description": "Per-panel outputs with signed URLs when ready" }, "error": { "anyOf": [ { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine error code" }, "message": { "type": "string", "description": "Human-readable error message" } }, "additionalProperties": false, "description": "Job-level error when status is failed" }, { "type": "null" } ], "description": "Job-level error details, or null when no job error is present" }, "createdAt": { "type": "string", "description": "ISO created timestamp" }, "updatedAt": { "type": "string", "description": "ISO updated timestamp" }, "deletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO soft-delete timestamp, or null" } }, "additionalProperties": false, "description": "GET /generations/:id response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } }, "delete": { "tags": [ "generation" ], "operationId": "generation.deleteGeneration", "parameters": [ { "name": "jobId", "in": "path", "schema": { "type": "string", "description": "Generation job id from the route path" }, "required": true, "description": "Generation job id from the route path" } ], "security": [], "responses": { "200": { "description": "DELETE /generations/:jobId response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "status" ], "properties": { "jobId": { "type": "string", "description": "Soft-deleted generation job id", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "status": { "type": "string", "enum": [ "deleted" ], "description": "Terminal deletion marker returned when the job was tombstoned" } }, "additionalProperties": false, "description": "DELETE /generations/:jobId response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/dashboard/generations": { "get": { "tags": [ "generation" ], "operationId": "generation.listDashboardGenerations", "parameters": [], "security": [], "responses": { "200": { "description": "GET /dashboard/generations response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "jobId", "status", "title", "prompt", "requestedCount", "appStoreUrl", "createdAt", "updatedAt" ], "properties": { "jobId": { "type": "string", "description": "Generation job id", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "status": { "type": "string", "enum": [ "queued", "processing", "succeeded", "failed", "deleted" ], "description": "Lifecycle status of the job" }, "title": { "type": "string", "description": "Short title derived from the user prompt" }, "prompt": { "type": "string", "description": "User art-direction prompt" }, "requestedCount": { "type": "integer", "description": "Panels requested", "title": "int" }, "appStoreUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional App Store URL used as a source" }, "createdAt": { "type": "string", "description": "ISO created timestamp" }, "updatedAt": { "type": "string", "description": "ISO updated timestamp" } }, "additionalProperties": false, "description": "One generation job summary for the dashboard list" }, "description": "Newest-first generation jobs for the signed-in user" } }, "additionalProperties": false, "description": "GET /dashboard/generations response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } }, "post": { "tags": [ "generation" ], "operationId": "generation.createDashboardGeneration", "parameters": [], "security": [], "responses": { "200": { "description": "POST /generations acknowledgement body", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "status" ], "properties": { "jobId": { "type": "string", "description": "Queued or replayed generation job id", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "status": { "type": "string", "description": "Job lifecycle status at acknowledge time (usually queued)", "title": "minLength(1)", "minLength": 1 }, "idempotentReplay": { "type": "boolean", "description": "True when an existing job was returned for the same Idempotency-Key" } }, "additionalProperties": false, "description": "POST /generations acknowledgement body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/dashboard/generations/{jobId}": { "get": { "tags": [ "generation" ], "operationId": "generation.getDashboardGenerationStatus", "parameters": [ { "name": "jobId", "in": "path", "schema": { "type": "string", "description": "Generation job id from the route path" }, "required": true, "description": "Generation job id from the route path" } ], "security": [], "responses": { "200": { "description": "GET /generations/:id response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "status", "requestedCount", "succeededCount", "failedCount", "creditsReserved", "creditsSpent", "creditsReleased", "outputs", "error", "createdAt", "updatedAt", "deletedAt" ], "properties": { "jobId": { "type": "string", "description": "Generation job id", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "status": { "type": "string", "enum": [ "queued", "processing", "succeeded", "failed", "deleted" ], "description": "Lifecycle status of the job" }, "requestedCount": { "type": "integer", "description": "Panels requested", "title": "int" }, "succeededCount": { "type": "integer", "description": "Panels that succeeded", "title": "int" }, "failedCount": { "type": "integer", "description": "Panels that failed", "title": "int" }, "creditsReserved": { "type": "integer", "description": "Credits held for this job", "title": "int" }, "creditsSpent": { "type": "integer", "description": "Credits charged for successes", "title": "int" }, "creditsReleased": { "type": "integer", "description": "Credits released on failure", "title": "int" }, "outputs": { "type": "array", "items": { "type": "object", "required": [ "id", "index", "status", "url", "expiresAt" ], "properties": { "id": { "type": "string", "description": "Identifier of the generated output asset", "title": "maxLength(80)", "minLength": 3, "maxLength": 80 }, "index": { "$ref": "#/components/schemas/Int", "description": "Zero-based panel index in the set", "title": "greaterThanOrEqualTo(0)", "minimum": 0 }, "status": { "type": "string", "enum": [ "succeeded", "failed", "deleted" ], "description": "Terminal status of this output" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Signed download URL, or null when unavailable" }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO expiry of the signed URL, or null" } }, "additionalProperties": false, "description": "One generated image on a generation job" }, "description": "Per-panel outputs with signed URLs when ready" }, "error": { "anyOf": [ { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine error code" }, "message": { "type": "string", "description": "Human-readable error message" } }, "additionalProperties": false, "description": "Job-level error when status is failed" }, { "type": "null" } ], "description": "Job-level error details, or null when no job error is present" }, "createdAt": { "type": "string", "description": "ISO created timestamp" }, "updatedAt": { "type": "string", "description": "ISO updated timestamp" }, "deletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO soft-delete timestamp, or null" } }, "additionalProperties": false, "description": "GET /generations/:id response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/outputs/{outputId}": { "get": { "tags": [ "generation" ], "operationId": "generation.getGenerationOutput", "parameters": [ { "name": "outputId", "in": "path", "schema": { "type": "string", "description": "Generated output id from the route path" }, "required": true, "description": "Generated output id from the route path" } ], "security": [], "responses": { "200": { "description": "Success", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/uploads/presign": { "post": { "tags": [ "generation" ], "operationId": "generation.presignGenerationUpload", "parameters": [], "security": [], "responses": { "200": { "description": "POST /uploads/presign response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "assetId", "uploadUrl", "expiresAt", "headers" ], "properties": { "assetId": { "type": "string", "description": "Uploaded asset identifier to pass into a generation request", "title": "maxLength(80)", "minLength": 3, "maxLength": 80 }, "uploadUrl": { "type": "string", "description": "Presigned URL for HTTP PUT" }, "expiresAt": { "type": "string", "description": "ISO expiry of the presigned URL" }, "headers": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "type": "string" }, "description": "Headers that must be sent with the PUT" } }, "additionalProperties": false, "description": "POST /uploads/presign response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "filename", "contentType", "byteSize" ], "properties": { "filename": { "type": "string", "description": "Original filename for the upload", "title": "maxLength(180)", "minLength": 1, "maxLength": 180 }, "contentType": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp" ], "description": "MIME type of the file body" }, "byteSize": { "$ref": "#/components/schemas/Int", "description": "Exact byte length of the file (1 B – 50 MiB)", "title": "between(1, 52428800)", "minimum": 1, "maximum": 52428800 } }, "additionalProperties": false, "description": "POST /uploads/presign request body" } } }, "required": true } } }, "/api/v1/dashboard/uploads/presign": { "post": { "tags": [ "generation" ], "operationId": "generation.presignDashboardUpload", "parameters": [], "security": [], "responses": { "200": { "description": "POST /uploads/presign response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "assetId", "uploadUrl", "expiresAt", "headers" ], "properties": { "assetId": { "type": "string", "description": "Uploaded asset identifier to pass into a generation request", "title": "maxLength(80)", "minLength": 3, "maxLength": 80 }, "uploadUrl": { "type": "string", "description": "Presigned URL for HTTP PUT" }, "expiresAt": { "type": "string", "description": "ISO expiry of the presigned URL" }, "headers": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "type": "string" }, "description": "Headers that must be sent with the PUT" } }, "additionalProperties": false, "description": "POST /uploads/presign response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/uploads/{assetId}": { "put": { "tags": [ "generation" ], "operationId": "generation.putGenerationUpload", "parameters": [ { "name": "assetId", "in": "path", "schema": { "type": "string", "description": "Uploaded source asset id from the route path" }, "required": true, "description": "Uploaded source asset id from the route path" } ], "security": [], "responses": { "200": { "description": "PUT /uploads/:assetId response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "assetId" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "Always true once the presigned upload bytes are stored" }, "assetId": { "type": "string", "description": "Stored uploaded source asset id now available to generation requests" } }, "additionalProperties": false, "description": "PUT /uploads/:assetId response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/internal/generator/claim": { "post": { "tags": [ "generation" ], "operationId": "generation.claimGeneratorJob", "parameters": [], "security": [], "responses": { "200": { "description": "POST /internal/generator/claim response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "job" ], "properties": { "job": { "anyOf": [ { "type": "object", "required": [ "api_key_id", "app_store_url", "claimed_at", "composed_prompt_snapshot", "created_at", "credits_released", "credits_spent", "deleted_at", "error_code", "error_message", "id", "idempotency_key", "requested_count", "reserved_credits", "status", "system_prompt_version", "updated_at", "user_id", "user_prompt", "uploaded_assets" ], "properties": { "api_key_id": { "type": "string", "description": "API key that submitted this generation" }, "app_store_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source App Store listing URL when the request used one" }, "claimed_at": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ], "description": "Epoch-millisecond timestamp when a generator claimed the queued job" }, "composed_prompt_snapshot": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Final server-composed prompt retained for generation diagnostics" }, "created_at": { "type": "integer", "description": "Epoch milliseconds when this job was created", "title": "int" }, "credits_released": { "type": "integer", "description": "Reserved credits returned at completion", "title": "int" }, "credits_spent": { "type": "integer", "description": "Credits charged for successful outputs", "title": "int" }, "deleted_at": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ], "description": "Epoch-millisecond soft-deletion timestamp for the generation job" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Terminal job failure code" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Operator-readable terminal failure message recorded for the job" }, "id": { "type": "string", "description": "Stable identifier of this persisted generation job", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "idempotency_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Caller key used to replay an earlier equivalent generation request" }, "requested_count": { "type": "integer", "description": "Output panels requested for this job", "title": "int" }, "reserved_credits": { "type": "integer", "description": "Credits held for this job", "title": "int" }, "status": { "type": "string", "enum": [ "queued", "processing", "succeeded", "failed", "deleted" ], "description": "Persisted job lifecycle state" }, "system_prompt_version": { "type": "string", "description": "Server-owned prompt revision used to compose this generation" }, "updated_at": { "type": "integer", "description": "Epoch milliseconds of the latest job change", "title": "int" }, "user_id": { "type": "string", "description": "Account that owns the generation job" }, "user_prompt": { "type": "string", "description": "Caller art direction stored with the job" }, "uploaded_assets": { "type": "array", "items": { "type": "object", "required": [ "byte_size", "content_type", "filename", "id" ], "properties": { "byte_size": { "type": "integer", "description": "Expected attached source byte length", "title": "int" }, "content_type": { "type": "string", "description": "Attached source MIME type" }, "filename": { "type": "string", "description": "Original source filename for the generator" }, "id": { "type": "string", "description": "Stable identifier of the attached uploaded source asset" } }, "additionalProperties": false, "description": "D1 uploaded-asset summary attached to a claimed generation job" }, "description": "Source assets attached to the claimed generation job" } }, "additionalProperties": false, "description": "Generator-facing claimed job plus its attached source assets" }, { "type": "null" } ], "description": "Claimed job payload, or null when the queue is empty" } }, "additionalProperties": false, "description": "POST /internal/generator/claim response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/internal/generator/assets/{assetId}": { "get": { "tags": [ "generation" ], "operationId": "generation.getGeneratorUploadedAsset", "parameters": [ { "name": "assetId", "in": "path", "schema": { "type": "string", "description": "Uploaded source asset id from the route path" }, "required": true, "description": "Uploaded source asset id from the route path" } ], "security": [], "responses": { "200": { "description": "Success", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/internal/generator/jobs/{jobId}/outputs/{index}": { "put": { "tags": [ "generation" ], "operationId": "generation.putGeneratorJobOutput", "parameters": [ { "name": "jobId", "in": "path", "schema": { "type": "string", "description": "Generation job id from the route path" }, "required": true, "description": "Generation job id from the route path" }, { "name": "index", "in": "path", "schema": { "type": "string", "description": "Zero-based output panel index from the path" }, "required": true, "description": "Zero-based output panel index from the path" } ], "security": [], "responses": { "200": { "description": "PUT /internal/generator/jobs/:jobId/outputs/:index response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "byteSize", "contentType", "r2Key" ], "properties": { "byteSize": { "type": "integer", "description": "Stored output object byte length", "title": "int" }, "contentType": { "type": "string", "description": "Stored output object MIME type" }, "r2Key": { "type": "string", "description": "Private generated-output R2 key" } }, "additionalProperties": false, "description": "PUT /internal/generator/jobs/:jobId/outputs/:index response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/internal/generator/jobs/{jobId}/complete": { "post": { "tags": [ "generation" ], "operationId": "generation.completeGeneratorJob", "parameters": [ { "name": "jobId", "in": "path", "schema": { "type": "string", "description": "Generation job id from the route path" }, "required": true, "description": "Generation job id from the route path" } ], "security": [], "responses": { "200": { "description": "POST /internal/generator/jobs/:jobId/complete response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "status" ], "properties": { "jobId": { "type": "string", "description": "Completed generation job id", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "status": { "type": "string", "enum": [ "queued", "processing", "succeeded", "failed", "deleted" ], "description": "Terminal job lifecycle state after completion" } }, "additionalProperties": false, "description": "POST /internal/generator/jobs/:jobId/complete response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/admin/generation-cost": { "get": { "tags": [ "generation" ], "operationId": "generation.getGenerationCostSummary", "parameters": [], "security": [], "responses": { "200": { "description": "GET /admin/generation-cost response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "samples", "avgCostUsd", "minCostUsd", "maxCostUsd", "totalCostUsd", "costMultiplier", "targetPriceCentsFromAvg", "note" ], "properties": { "samples": { "$ref": "#/components/schemas/Int", "description": "Succeeded outputs with a stored estimated_cost_usd", "title": "greaterThanOrEqualTo(0)", "minimum": 0 }, "avgCostUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Average estimated provider cost in USD, or null when samples is 0" }, "minCostUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Minimum estimated cost in USD among samples" }, "maxCostUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Maximum estimated cost in USD among samples" }, "totalCostUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Sum of estimated costs in USD among samples" }, "costMultiplier": { "type": "number", "description": "ADR-0026 list-price multiplier applied to measured cost (1.5)" }, "targetPriceCentsFromAvg": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ], "description": "round(avgCostUsd×100)×1.5 list target per image in cents; null when no samples" }, "note": { "type": "string", "description": "How to remeasure and when CREDIT_PACKS may be updated" } }, "additionalProperties": false, "description": "GET /admin/generation-cost response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/auth/google": { "get": { "tags": [ "auth" ], "operationId": "auth.beginGoogleOAuth", "parameters": [], "security": [], "responses": { "302": { "description": "Success" }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/auth/google/callback": { "get": { "tags": [ "auth" ], "operationId": "auth.finishGoogleOAuth", "parameters": [], "security": [], "responses": { "302": { "description": "Success" }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/auth/me": { "get": { "tags": [ "auth" ], "operationId": "auth.getSessionUser", "parameters": [], "security": [], "responses": { "200": { "description": "Authenticated GET /auth/me response variant", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "authenticated", "user", "session" ], "properties": { "authenticated": { "type": "boolean", "enum": [ true ], "description": "Indicates that the dashboard session is authenticated" }, "user": { "type": "object", "required": [ "id", "email", "displayName", "avatarUrl", "creditBalance" ], "properties": { "id": { "type": "string", "description": "Authenticated dashboard user identifier" }, "email": { "type": "string", "description": "Email address shown in the dashboard" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name from the identity provider, or null when unavailable" }, "avatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Avatar URL from the identity provider, or null when unavailable" }, "creditBalance": { "type": "integer", "description": "Current spendable credit balance", "title": "int" } }, "additionalProperties": false, "description": "Authenticated dashboard user details" }, "session": { "type": "object", "required": [ "expiresAt" ], "properties": { "expiresAt": { "type": "string", "description": "ISO timestamp when the dashboard session expires" } }, "additionalProperties": false, "description": "Authenticated dashboard session metadata" } }, "additionalProperties": false, "description": "Authenticated GET /auth/me response variant" }, { "type": "object", "required": [ "authenticated", "user", "session" ], "properties": { "authenticated": { "type": "boolean", "enum": [ false ], "description": "Indicates that no dashboard session is authenticated" }, "user": { "type": "null", "description": "Null user sentinel for an unauthenticated dashboard request" }, "session": { "type": "null", "description": "Null session sentinel for an unauthenticated dashboard request" } }, "additionalProperties": false, "description": "Unauthenticated GET /auth/me response variant" } ] } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/auth/logout": { "post": { "tags": [ "auth" ], "operationId": "auth.logout", "parameters": [], "security": [], "responses": { "200": { "description": "POST /auth/logout acknowledgement body", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "Always true once the dashboard session cookie has been cleared" } }, "additionalProperties": false, "description": "POST /auth/logout acknowledgement body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } }, "get": { "tags": [ "auth" ], "operationId": "auth.logoutRedirect", "parameters": [], "security": [], "responses": { "302": { "description": "Success" }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/auth/cli/device/start": { "post": { "tags": [ "auth" ], "operationId": "auth.startCliDevice", "parameters": [], "security": [], "responses": { "200": { "description": "POST /auth/cli/device/start response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "deviceCode", "userCode", "verificationUrl", "expiresIn", "interval" ], "properties": { "deviceCode": { "type": "string", "description": "Secret device code the CLI polls with (never display to the user)", "title": "minLength(16)", "minLength": 16 }, "userCode": { "type": "string", "description": "Short user code shown in the terminal (also embedded in verificationUrl)", "title": "minLength(4)", "minLength": 4 }, "verificationUrl": { "type": "string", "description": "Browser URL that starts Google OAuth for this device login", "title": "minLength(8)", "minLength": 8 }, "expiresIn": { "$ref": "#/components/schemas/Int", "description": "Seconds until the device code expires", "title": "greaterThan(0)", "exclusiveMinimum": 0 }, "interval": { "$ref": "#/components/schemas/Int", "description": "Minimum seconds the CLI should wait between poll attempts", "title": "greaterThan(0)", "exclusiveMinimum": 0 } }, "additionalProperties": false, "description": "POST /auth/cli/device/start response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "mode": { "type": "string", "enum": [ "test", "live" ], "description": "API-key mode to mint after Google OAuth (`live` or `test`)" } }, "additionalProperties": false, "description": "POST /auth/cli/device/start request body" } } }, "required": true } } }, "/api/v1/auth/cli/device/poll": { "post": { "tags": [ "auth" ], "operationId": "auth.pollCliDevice", "parameters": [], "security": [], "responses": { "200": { "description": "CLI device poll still waiting for browser OAuth", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending" ], "description": "User has not finished browser OAuth yet" } }, "additionalProperties": false, "description": "CLI device poll still waiting for browser OAuth" }, { "type": "object", "required": [ "status", "userId", "email", "apiKey", "apiKeyId", "mode", "balance", "created" ], "properties": { "status": { "type": "string", "enum": [ "complete" ], "description": "Browser OAuth finished; API key is included once" }, "userId": { "type": "string", "description": "Authenticated user id", "title": "maxLength(80)", "minLength": 3, "maxLength": 80 }, "email": { "type": "string", "description": "Authenticated email (from Google)" }, "apiKey": { "type": "string", "description": "Plaintext `gsk_` API key (shown once; store immediately)", "title": "minLength(1)", "minLength": 1 }, "apiKeyId": { "type": "string", "description": "Persisted API key id", "title": "maxLength(80)", "minLength": 3, "maxLength": 80 }, "mode": { "type": "string", "enum": [ "test", "live" ], "description": "Minted key mode" }, "balance": { "type": "integer", "description": "Credit balance after login", "title": "int" }, "created": { "type": "boolean", "description": "True when this login created the user account" } }, "additionalProperties": false, "description": "CLI device poll complete — same identity fields as email OTP verify" } ] } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "deviceCode" ], "properties": { "deviceCode": { "type": "string", "description": "Secret device code issued by /auth/cli/device/start", "title": "minLength(16)", "minLength": 16 } }, "additionalProperties": false, "description": "POST /auth/cli/device/poll request body" } } }, "required": true } } }, "/api/v1/auth/cli/device/authorize": { "get": { "tags": [ "auth" ], "operationId": "auth.authorizeCliDevice", "parameters": [], "security": [], "responses": { "302": { "description": "Success" }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/auth/cli/device/done": { "get": { "tags": [ "auth" ], "operationId": "auth.cliDeviceDone", "parameters": [], "security": [], "responses": { "200": { "description": "Success" }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/auth/email/start": { "post": { "tags": [ "auth" ], "operationId": "auth.startEmailOtp", "parameters": [], "security": [], "responses": { "200": { "description": "POST /auth/email/start response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "expiresInSeconds", "resendAfterSeconds" ], "properties": { "email": { "type": "string", "description": "Normalized email address receiving the login code" }, "expiresInSeconds": { "$ref": "#/components/schemas/Int", "description": "Seconds until the issued login code expires", "title": "greaterThan(0)", "exclusiveMinimum": 0 }, "resendAfterSeconds": { "$ref": "#/components/schemas/Int", "description": "Seconds before another login code may be requested", "title": "greaterThanOrEqualTo(0)", "minimum": 0 }, "devCode": { "type": "string", "description": "Development-only login code when local disclosure is enabled" } }, "additionalProperties": false, "description": "POST /auth/email/start response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Email address that will receive the login code" } }, "additionalProperties": false, "description": "POST /auth/email/start request body" } } }, "required": true } } }, "/api/v1/auth/email/verify": { "post": { "tags": [ "auth" ], "operationId": "auth.verifyEmailOtp", "parameters": [], "security": [], "responses": { "200": { "description": "POST /auth/email/verify response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "userId", "email", "apiKey", "apiKeyId", "mode", "balance", "created" ], "properties": { "userId": { "type": "string", "description": "Authenticated user account identifier", "title": "maxLength(80)", "minLength": 3, "maxLength": 80 }, "email": { "type": "string", "description": "Authenticated normalized email address" }, "apiKey": { "type": "string", "description": "Plaintext API key returned once for immediate storage", "title": "minLength(1)", "minLength": 1 }, "apiKeyId": { "type": "string", "description": "Identifier of the persisted API key", "title": "maxLength(80)", "minLength": 3, "maxLength": 80 }, "mode": { "type": "string", "enum": [ "test", "live" ], "description": "Operating mode of the minted API key" }, "balance": { "type": "integer", "description": "Spendable credit balance after login", "title": "int" }, "created": { "type": "boolean", "description": "Whether verification created a new user account" } }, "additionalProperties": false, "description": "POST /auth/email/verify response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "code" ], "properties": { "email": { "type": "string", "description": "Email address associated with the login code" }, "code": { "type": "string", "description": "Six-digit login code sent to the email address" }, "mode": { "type": "string", "enum": [ "test", "live" ], "description": "API-key mode to mint after verification, defaulting to live" } }, "additionalProperties": false, "description": "POST /auth/email/verify request body" } } }, "required": true } } }, "/api/v1/dashboard/preferences": { "get": { "tags": [ "account" ], "operationId": "account.getDashboardPreferences", "parameters": [], "security": [], "responses": { "200": { "description": "GET /dashboard/preferences response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "defaultSystemPrompt", "defaultOutputCount", "emailReceipts", "keepOriginals", "theme", "totpEnabled" ], "properties": { "defaultSystemPrompt": { "type": "string", "description": "Optional short house-style prepended to every generation prompt (max 500 chars; keep concise)", "title": "maxLength(500)", "maxLength": 500 }, "defaultOutputCount": { "$ref": "#/components/schemas/Int", "description": "Default panel count for new chat composers", "title": "between(1, 6)", "minimum": 1, "maximum": 6 }, "emailReceipts": { "type": "boolean", "description": "Whether to email generation receipts" }, "keepOriginals": { "type": "boolean", "description": "Whether to keep source screenshots attached to jobs" }, "theme": { "type": "string", "enum": [ "light", "dark", "system" ], "description": "Preferred UI theme" }, "totpEnabled": { "type": "boolean", "description": "Whether authenticator 2FA is enabled for this account" } }, "additionalProperties": false, "description": "GET /dashboard/preferences response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } }, "patch": { "tags": [ "account" ], "operationId": "account.patchDashboardPreferences", "parameters": [], "security": [], "responses": { "200": { "description": "GET /dashboard/preferences response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "defaultSystemPrompt", "defaultOutputCount", "emailReceipts", "keepOriginals", "theme", "totpEnabled" ], "properties": { "defaultSystemPrompt": { "type": "string", "description": "Optional short house-style prepended to every generation prompt (max 500 chars; keep concise)", "title": "maxLength(500)", "maxLength": 500 }, "defaultOutputCount": { "$ref": "#/components/schemas/Int", "description": "Default panel count for new chat composers", "title": "between(1, 6)", "minimum": 1, "maximum": 6 }, "emailReceipts": { "type": "boolean", "description": "Whether to email generation receipts" }, "keepOriginals": { "type": "boolean", "description": "Whether to keep source screenshots attached to jobs" }, "theme": { "type": "string", "enum": [ "light", "dark", "system" ], "description": "Preferred UI theme" }, "totpEnabled": { "type": "boolean", "description": "Whether authenticator 2FA is enabled for this account" } }, "additionalProperties": false, "description": "GET /dashboard/preferences response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "defaultSystemPrompt": { "type": "string", "description": "Optional short house-style prepended to every generation prompt (max 500 chars)", "title": "maxLength(500)", "maxLength": 500 }, "defaultOutputCount": { "allOf": [ { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 6", "title": "between(1, 6)", "minimum": 1, "maximum": 6 } ], "description": "Default panel count for new chat composers" }, "emailReceipts": { "type": "boolean", "description": "Whether to email generation receipts" }, "keepOriginals": { "type": "boolean", "description": "Whether to keep source screenshots attached to jobs" }, "theme": { "type": "string", "enum": [ "light", "dark", "system" ], "description": "Preferred UI theme" } }, "additionalProperties": false, "description": "PATCH /dashboard/preferences request body" } } }, "required": true } } }, "/api/v1/dashboard/security/totp/setup": { "post": { "tags": [ "account" ], "operationId": "account.setupDashboardTotp", "parameters": [], "security": [], "responses": { "200": { "description": "POST /dashboard/security/totp/setup response", "content": { "application/json": { "schema": { "type": "object", "required": [ "otpauthUrl", "secret" ], "properties": { "otpauthUrl": { "type": "string", "description": "otpauth:// URI for authenticator apps" }, "secret": { "type": "string", "description": "Base32 secret shown once for manual entry" } }, "additionalProperties": false, "description": "POST /dashboard/security/totp/setup response" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/dashboard/security/totp/confirm": { "post": { "tags": [ "account" ], "operationId": "account.confirmDashboardTotp", "parameters": [], "security": [], "responses": { "200": { "description": "GET /dashboard/preferences response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "defaultSystemPrompt", "defaultOutputCount", "emailReceipts", "keepOriginals", "theme", "totpEnabled" ], "properties": { "defaultSystemPrompt": { "type": "string", "description": "Optional short house-style prepended to every generation prompt (max 500 chars; keep concise)", "title": "maxLength(500)", "maxLength": 500 }, "defaultOutputCount": { "$ref": "#/components/schemas/Int", "description": "Default panel count for new chat composers", "title": "between(1, 6)", "minimum": 1, "maximum": 6 }, "emailReceipts": { "type": "boolean", "description": "Whether to email generation receipts" }, "keepOriginals": { "type": "boolean", "description": "Whether to keep source screenshots attached to jobs" }, "theme": { "type": "string", "enum": [ "light", "dark", "system" ], "description": "Preferred UI theme" }, "totpEnabled": { "type": "boolean", "description": "Whether authenticator 2FA is enabled for this account" } }, "additionalProperties": false, "description": "GET /dashboard/preferences response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "Six-digit TOTP code from the authenticator app", "pattern": "^\\d{6}$" } }, "additionalProperties": false, "description": "TOTP code request body" } } }, "required": true } } }, "/api/v1/dashboard/security/totp/disable": { "post": { "tags": [ "account" ], "operationId": "account.disableDashboardTotp", "parameters": [], "security": [], "responses": { "200": { "description": "GET /dashboard/preferences response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "defaultSystemPrompt", "defaultOutputCount", "emailReceipts", "keepOriginals", "theme", "totpEnabled" ], "properties": { "defaultSystemPrompt": { "type": "string", "description": "Optional short house-style prepended to every generation prompt (max 500 chars; keep concise)", "title": "maxLength(500)", "maxLength": 500 }, "defaultOutputCount": { "$ref": "#/components/schemas/Int", "description": "Default panel count for new chat composers", "title": "between(1, 6)", "minimum": 1, "maximum": 6 }, "emailReceipts": { "type": "boolean", "description": "Whether to email generation receipts" }, "keepOriginals": { "type": "boolean", "description": "Whether to keep source screenshots attached to jobs" }, "theme": { "type": "string", "enum": [ "light", "dark", "system" ], "description": "Preferred UI theme" }, "totpEnabled": { "type": "boolean", "description": "Whether authenticator 2FA is enabled for this account" } }, "additionalProperties": false, "description": "GET /dashboard/preferences response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "Six-digit TOTP code from the authenticator app", "pattern": "^\\d{6}$" } }, "additionalProperties": false, "description": "TOTP code request body" } } }, "required": true } } }, "/api/v1/dashboard/onboarding": { "get": { "tags": [ "account" ], "operationId": "account.getDashboardOnboarding", "parameters": [], "security": [], "responses": { "200": { "description": "GET /dashboard/onboarding response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "surveyCompleted", "walkthroughDismissed", "survey" ], "properties": { "surveyCompleted": { "type": "boolean", "description": "True once the mandatory survey has been submitted" }, "walkthroughDismissed": { "type": "boolean", "description": "True once the skippable product walkthrough was completed or skipped" }, "survey": { "anyOf": [ { "type": "object", "required": [ "referralSource", "role", "painPoint", "stores", "monthlyVolume" ], "properties": { "referralSource": { "type": "string", "enum": [ "twitter_x", "linkedin", "reddit", "producthunt", "youtube", "github", "hackernews", "tiktok", "instagram", "discord_slack", "google_search", "friend", "ai_assistant", "in_the_wild", "blog_newsletter", "other" ], "description": "Stable code for where the user first heard about genshot" }, "referralDetail": { "type": "string", "description": "Free-text detail for friend / other / AI / blog / in-the-wild sources", "title": "maxLength(200)", "maxLength": 200 }, "role": { "type": "string", "enum": [ "indie_dev", "founder", "agency", "marketer", "designer", "pm", "hobbyist", "other" ], "description": "Self-described persona of the user" }, "painPoint": { "type": "string", "enum": [ "store_screenshots", "aso", "localization", "design_time", "cost", "brand_consistency", "other" ], "description": "Primary problem the user wants genshot to solve" }, "stores": { "type": "array", "items": { "type": "string", "enum": [ "appstore", "play", "chrome" ], "description": "App Store / Google Play / Chrome Web Store target" }, "description": "One or more store targets the user publishes to", "title": "minItems(1)", "minItems": 1 }, "monthlyVolume": { "type": "string", "enum": [ "one", "few", "some", "many" ], "description": "Apps per month bucket: one=1, few=2-5, some=6-20, many=20+" } }, "additionalProperties": false, "description": "POST /dashboard/onboarding/survey request body" }, { "type": "null" } ], "description": "Stored survey answers, or null before submission" } }, "additionalProperties": false, "description": "GET /dashboard/onboarding response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/dashboard/onboarding/survey": { "post": { "tags": [ "account" ], "operationId": "account.submitDashboardSurvey", "parameters": [], "security": [], "responses": { "200": { "description": "GET /dashboard/onboarding response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "surveyCompleted", "walkthroughDismissed", "survey" ], "properties": { "surveyCompleted": { "type": "boolean", "description": "True once the mandatory survey has been submitted" }, "walkthroughDismissed": { "type": "boolean", "description": "True once the skippable product walkthrough was completed or skipped" }, "survey": { "anyOf": [ { "type": "object", "required": [ "referralSource", "role", "painPoint", "stores", "monthlyVolume" ], "properties": { "referralSource": { "type": "string", "enum": [ "twitter_x", "linkedin", "reddit", "producthunt", "youtube", "github", "hackernews", "tiktok", "instagram", "discord_slack", "google_search", "friend", "ai_assistant", "in_the_wild", "blog_newsletter", "other" ], "description": "Stable code for where the user first heard about genshot" }, "referralDetail": { "type": "string", "description": "Free-text detail for friend / other / AI / blog / in-the-wild sources", "title": "maxLength(200)", "maxLength": 200 }, "role": { "type": "string", "enum": [ "indie_dev", "founder", "agency", "marketer", "designer", "pm", "hobbyist", "other" ], "description": "Self-described persona of the user" }, "painPoint": { "type": "string", "enum": [ "store_screenshots", "aso", "localization", "design_time", "cost", "brand_consistency", "other" ], "description": "Primary problem the user wants genshot to solve" }, "stores": { "type": "array", "items": { "type": "string", "enum": [ "appstore", "play", "chrome" ], "description": "App Store / Google Play / Chrome Web Store target" }, "description": "One or more store targets the user publishes to", "title": "minItems(1)", "minItems": 1 }, "monthlyVolume": { "type": "string", "enum": [ "one", "few", "some", "many" ], "description": "Apps per month bucket: one=1, few=2-5, some=6-20, many=20+" } }, "additionalProperties": false, "description": "POST /dashboard/onboarding/survey request body" }, { "type": "null" } ], "description": "Stored survey answers, or null before submission" } }, "additionalProperties": false, "description": "GET /dashboard/onboarding response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "referralSource", "role", "painPoint", "stores", "monthlyVolume" ], "properties": { "referralSource": { "type": "string", "enum": [ "twitter_x", "linkedin", "reddit", "producthunt", "youtube", "github", "hackernews", "tiktok", "instagram", "discord_slack", "google_search", "friend", "ai_assistant", "in_the_wild", "blog_newsletter", "other" ], "description": "Stable code for where the user first heard about genshot" }, "referralDetail": { "type": "string", "description": "Free-text detail for friend / other / AI / blog / in-the-wild sources", "title": "maxLength(200)", "maxLength": 200 }, "role": { "type": "string", "enum": [ "indie_dev", "founder", "agency", "marketer", "designer", "pm", "hobbyist", "other" ], "description": "Self-described persona of the user" }, "painPoint": { "type": "string", "enum": [ "store_screenshots", "aso", "localization", "design_time", "cost", "brand_consistency", "other" ], "description": "Primary problem the user wants genshot to solve" }, "stores": { "type": "array", "items": { "type": "string", "enum": [ "appstore", "play", "chrome" ], "description": "App Store / Google Play / Chrome Web Store target" }, "description": "One or more store targets the user publishes to", "title": "minItems(1)", "minItems": 1 }, "monthlyVolume": { "type": "string", "enum": [ "one", "few", "some", "many" ], "description": "Apps per month bucket: one=1, few=2-5, some=6-20, many=20+" } }, "additionalProperties": false, "description": "POST /dashboard/onboarding/survey request body" } } }, "required": true } } }, "/api/v1/dashboard/onboarding/walkthrough/dismiss": { "post": { "tags": [ "account" ], "operationId": "account.dismissDashboardWalkthrough", "parameters": [], "security": [], "responses": { "200": { "description": "GET /dashboard/onboarding response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "surveyCompleted", "walkthroughDismissed", "survey" ], "properties": { "surveyCompleted": { "type": "boolean", "description": "True once the mandatory survey has been submitted" }, "walkthroughDismissed": { "type": "boolean", "description": "True once the skippable product walkthrough was completed or skipped" }, "survey": { "anyOf": [ { "type": "object", "required": [ "referralSource", "role", "painPoint", "stores", "monthlyVolume" ], "properties": { "referralSource": { "type": "string", "enum": [ "twitter_x", "linkedin", "reddit", "producthunt", "youtube", "github", "hackernews", "tiktok", "instagram", "discord_slack", "google_search", "friend", "ai_assistant", "in_the_wild", "blog_newsletter", "other" ], "description": "Stable code for where the user first heard about genshot" }, "referralDetail": { "type": "string", "description": "Free-text detail for friend / other / AI / blog / in-the-wild sources", "title": "maxLength(200)", "maxLength": 200 }, "role": { "type": "string", "enum": [ "indie_dev", "founder", "agency", "marketer", "designer", "pm", "hobbyist", "other" ], "description": "Self-described persona of the user" }, "painPoint": { "type": "string", "enum": [ "store_screenshots", "aso", "localization", "design_time", "cost", "brand_consistency", "other" ], "description": "Primary problem the user wants genshot to solve" }, "stores": { "type": "array", "items": { "type": "string", "enum": [ "appstore", "play", "chrome" ], "description": "App Store / Google Play / Chrome Web Store target" }, "description": "One or more store targets the user publishes to", "title": "minItems(1)", "minItems": 1 }, "monthlyVolume": { "type": "string", "enum": [ "one", "few", "some", "many" ], "description": "Apps per month bucket: one=1, few=2-5, some=6-20, many=20+" } }, "additionalProperties": false, "description": "POST /dashboard/onboarding/survey request body" }, { "type": "null" } ], "description": "Stored survey answers, or null before submission" } }, "additionalProperties": false, "description": "GET /dashboard/onboarding response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/onboarding": { "get": { "tags": [ "account" ], "operationId": "account.getOnboarding", "parameters": [], "security": [], "responses": { "200": { "description": "GET /dashboard/onboarding response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "surveyCompleted", "walkthroughDismissed", "survey" ], "properties": { "surveyCompleted": { "type": "boolean", "description": "True once the mandatory survey has been submitted" }, "walkthroughDismissed": { "type": "boolean", "description": "True once the skippable product walkthrough was completed or skipped" }, "survey": { "anyOf": [ { "type": "object", "required": [ "referralSource", "role", "painPoint", "stores", "monthlyVolume" ], "properties": { "referralSource": { "type": "string", "enum": [ "twitter_x", "linkedin", "reddit", "producthunt", "youtube", "github", "hackernews", "tiktok", "instagram", "discord_slack", "google_search", "friend", "ai_assistant", "in_the_wild", "blog_newsletter", "other" ], "description": "Stable code for where the user first heard about genshot" }, "referralDetail": { "type": "string", "description": "Free-text detail for friend / other / AI / blog / in-the-wild sources", "title": "maxLength(200)", "maxLength": 200 }, "role": { "type": "string", "enum": [ "indie_dev", "founder", "agency", "marketer", "designer", "pm", "hobbyist", "other" ], "description": "Self-described persona of the user" }, "painPoint": { "type": "string", "enum": [ "store_screenshots", "aso", "localization", "design_time", "cost", "brand_consistency", "other" ], "description": "Primary problem the user wants genshot to solve" }, "stores": { "type": "array", "items": { "type": "string", "enum": [ "appstore", "play", "chrome" ], "description": "App Store / Google Play / Chrome Web Store target" }, "description": "One or more store targets the user publishes to", "title": "minItems(1)", "minItems": 1 }, "monthlyVolume": { "type": "string", "enum": [ "one", "few", "some", "many" ], "description": "Apps per month bucket: one=1, few=2-5, some=6-20, many=20+" } }, "additionalProperties": false, "description": "POST /dashboard/onboarding/survey request body" }, { "type": "null" } ], "description": "Stored survey answers, or null before submission" } }, "additionalProperties": false, "description": "GET /dashboard/onboarding response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/onboarding/survey": { "post": { "tags": [ "account" ], "operationId": "account.submitOnboardingSurvey", "parameters": [], "security": [], "responses": { "200": { "description": "GET /dashboard/onboarding response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "surveyCompleted", "walkthroughDismissed", "survey" ], "properties": { "surveyCompleted": { "type": "boolean", "description": "True once the mandatory survey has been submitted" }, "walkthroughDismissed": { "type": "boolean", "description": "True once the skippable product walkthrough was completed or skipped" }, "survey": { "anyOf": [ { "type": "object", "required": [ "referralSource", "role", "painPoint", "stores", "monthlyVolume" ], "properties": { "referralSource": { "type": "string", "enum": [ "twitter_x", "linkedin", "reddit", "producthunt", "youtube", "github", "hackernews", "tiktok", "instagram", "discord_slack", "google_search", "friend", "ai_assistant", "in_the_wild", "blog_newsletter", "other" ], "description": "Stable code for where the user first heard about genshot" }, "referralDetail": { "type": "string", "description": "Free-text detail for friend / other / AI / blog / in-the-wild sources", "title": "maxLength(200)", "maxLength": 200 }, "role": { "type": "string", "enum": [ "indie_dev", "founder", "agency", "marketer", "designer", "pm", "hobbyist", "other" ], "description": "Self-described persona of the user" }, "painPoint": { "type": "string", "enum": [ "store_screenshots", "aso", "localization", "design_time", "cost", "brand_consistency", "other" ], "description": "Primary problem the user wants genshot to solve" }, "stores": { "type": "array", "items": { "type": "string", "enum": [ "appstore", "play", "chrome" ], "description": "App Store / Google Play / Chrome Web Store target" }, "description": "One or more store targets the user publishes to", "title": "minItems(1)", "minItems": 1 }, "monthlyVolume": { "type": "string", "enum": [ "one", "few", "some", "many" ], "description": "Apps per month bucket: one=1, few=2-5, some=6-20, many=20+" } }, "additionalProperties": false, "description": "POST /dashboard/onboarding/survey request body" }, { "type": "null" } ], "description": "Stored survey answers, or null before submission" } }, "additionalProperties": false, "description": "GET /dashboard/onboarding response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "referralSource", "role", "painPoint", "stores", "monthlyVolume" ], "properties": { "referralSource": { "type": "string", "enum": [ "twitter_x", "linkedin", "reddit", "producthunt", "youtube", "github", "hackernews", "tiktok", "instagram", "discord_slack", "google_search", "friend", "ai_assistant", "in_the_wild", "blog_newsletter", "other" ], "description": "Stable code for where the user first heard about genshot" }, "referralDetail": { "type": "string", "description": "Free-text detail for friend / other / AI / blog / in-the-wild sources", "title": "maxLength(200)", "maxLength": 200 }, "role": { "type": "string", "enum": [ "indie_dev", "founder", "agency", "marketer", "designer", "pm", "hobbyist", "other" ], "description": "Self-described persona of the user" }, "painPoint": { "type": "string", "enum": [ "store_screenshots", "aso", "localization", "design_time", "cost", "brand_consistency", "other" ], "description": "Primary problem the user wants genshot to solve" }, "stores": { "type": "array", "items": { "type": "string", "enum": [ "appstore", "play", "chrome" ], "description": "App Store / Google Play / Chrome Web Store target" }, "description": "One or more store targets the user publishes to", "title": "minItems(1)", "minItems": 1 }, "monthlyVolume": { "type": "string", "enum": [ "one", "few", "some", "many" ], "description": "Apps per month bucket: one=1, few=2-5, some=6-20, many=20+" } }, "additionalProperties": false, "description": "POST /dashboard/onboarding/survey request body" } } }, "required": true } } }, "/api/v1/onboarding/walkthrough/dismiss": { "post": { "tags": [ "account" ], "operationId": "account.dismissOnboardingTour", "parameters": [], "security": [], "responses": { "200": { "description": "GET /dashboard/onboarding response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "surveyCompleted", "walkthroughDismissed", "survey" ], "properties": { "surveyCompleted": { "type": "boolean", "description": "True once the mandatory survey has been submitted" }, "walkthroughDismissed": { "type": "boolean", "description": "True once the skippable product walkthrough was completed or skipped" }, "survey": { "anyOf": [ { "type": "object", "required": [ "referralSource", "role", "painPoint", "stores", "monthlyVolume" ], "properties": { "referralSource": { "type": "string", "enum": [ "twitter_x", "linkedin", "reddit", "producthunt", "youtube", "github", "hackernews", "tiktok", "instagram", "discord_slack", "google_search", "friend", "ai_assistant", "in_the_wild", "blog_newsletter", "other" ], "description": "Stable code for where the user first heard about genshot" }, "referralDetail": { "type": "string", "description": "Free-text detail for friend / other / AI / blog / in-the-wild sources", "title": "maxLength(200)", "maxLength": 200 }, "role": { "type": "string", "enum": [ "indie_dev", "founder", "agency", "marketer", "designer", "pm", "hobbyist", "other" ], "description": "Self-described persona of the user" }, "painPoint": { "type": "string", "enum": [ "store_screenshots", "aso", "localization", "design_time", "cost", "brand_consistency", "other" ], "description": "Primary problem the user wants genshot to solve" }, "stores": { "type": "array", "items": { "type": "string", "enum": [ "appstore", "play", "chrome" ], "description": "App Store / Google Play / Chrome Web Store target" }, "description": "One or more store targets the user publishes to", "title": "minItems(1)", "minItems": 1 }, "monthlyVolume": { "type": "string", "enum": [ "one", "few", "some", "many" ], "description": "Apps per month bucket: one=1, few=2-5, some=6-20, many=20+" } }, "additionalProperties": false, "description": "POST /dashboard/onboarding/survey request body" }, { "type": "null" } ], "description": "Stored survey answers, or null before submission" } }, "additionalProperties": false, "description": "GET /dashboard/onboarding response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/admin/beta-users": { "post": { "tags": [ "account" ], "operationId": "account.createBetaUser", "parameters": [], "security": [], "responses": { "200": { "description": "POST /admin/beta-users response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "apiKey", "apiKeyId", "balance", "email", "userId" ], "properties": { "apiKey": { "type": "string", "description": "One-shot plaintext API key, shown only in this response" }, "apiKeyId": { "type": "string", "description": "Identifier of the API key minted for the beta user" }, "balance": { "type": "integer", "description": "Credit balance granted to the beta user on creation", "title": "int" }, "email": { "type": "string", "description": "Normalized email address of the seeded beta user" }, "userId": { "type": "string", "description": "Account identifier of the seeded beta user" } }, "additionalProperties": false, "description": "POST /admin/beta-users response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Normalized email address for the beta user" }, "mode": { "type": "string", "enum": [ "test", "live" ], "description": "API-key mode assigned to the beta user, defaulting to test" }, "freeCredits": { "allOf": [ { "$ref": "#/components/schemas/Int", "description": "a number between 0 and 1000", "title": "between(0, 1000)", "minimum": 0, "maximum": 1000 } ], "description": "Initial free-credit balance, defaulting to the beta allowance" } }, "additionalProperties": false, "description": "POST /admin/beta-users request body" } } }, "required": true } } }, "/api/v1/admin/users/{id}": { "get": { "tags": [ "account" ], "operationId": "account.getUser", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "description": "Account identifier from the route path" }, "required": true, "description": "Account identifier from the route path" } ], "security": [], "responses": { "200": { "description": "GET /admin/users/:id response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "anyOf": [ { "type": "object", "required": [ "created_at", "credit_balance", "email", "id", "lemon_customer_id", "updated_at" ], "properties": { "created_at": { "type": "integer", "description": "Epoch milliseconds when the account was created", "title": "int" }, "credit_balance": { "type": "integer", "description": "Current generation-credit balance shown to administrators", "title": "int" }, "email": { "type": "string", "description": "Stored account email shown to administrators" }, "id": { "type": "string", "description": "Account identifier selected by the administrative lookup" }, "lemon_customer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lemon customer identifier linked to the account when available" }, "updated_at": { "type": "integer", "description": "Epoch milliseconds of the latest account update", "title": "int" } }, "additionalProperties": false, "description": "D1 user projection returned by an administrative account lookup" }, { "type": "null" } ], "description": "Administrative user projection, or null when no account matches the id" } }, "additionalProperties": false, "description": "GET /admin/users/:id response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/admin/users/{id}/credits": { "post": { "tags": [ "account" ], "operationId": "account.grantUserCredits", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "description": "Account identifier from the route path" }, "required": true, "description": "Account identifier from the route path" } ], "security": [], "responses": { "200": { "description": "POST /admin/users/:id/credits response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "balance", "ledgerId" ], "properties": { "balance": { "type": "integer", "description": "Credit balance after the manual grant or adjustment was applied", "title": "int" }, "ledgerId": { "type": "string", "description": "Identifier of the credit-ledger entry written for the adjustment" } }, "additionalProperties": false, "description": "POST /admin/users/:id/credits response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "$ref": "#/components/schemas/Int", "description": "Signed credit adjustment between -10,000 and 10,000", "title": "between(-10000, 10000)", "minimum": -10000, "maximum": 10000 }, "note": { "type": "string", "description": "Optional operator note explaining the credit adjustment", "title": "maxLength(500)", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false, "description": "POST /admin/users/:id/credits request body" } } }, "required": true } } }, "/api/v1/admin/jobs/{id}": { "get": { "tags": [ "account" ], "operationId": "account.getJob", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "description": "Generation job id from the route path" }, "required": true, "description": "Generation job id from the route path" } ], "security": [], "responses": { "200": { "description": "GET /admin/jobs/:id response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "job", "outputs" ], "properties": { "job": { "anyOf": [ { "type": "object", "required": [ "api_key_id", "app_store_url", "claimed_at", "composed_prompt_snapshot", "created_at", "credits_released", "credits_spent", "deleted_at", "error_code", "error_message", "id", "idempotency_key", "requested_count", "reserved_credits", "status", "system_prompt_version", "updated_at", "user_id", "user_prompt" ], "properties": { "api_key_id": { "type": "string", "description": "API key that submitted this generation" }, "app_store_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source App Store listing URL when the request used one" }, "claimed_at": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ], "description": "Epoch-millisecond timestamp when a generator claimed the queued job" }, "composed_prompt_snapshot": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Final server-composed prompt retained for generation diagnostics" }, "created_at": { "type": "integer", "description": "Epoch milliseconds when this job was created", "title": "int" }, "credits_released": { "type": "integer", "description": "Reserved credits returned at completion", "title": "int" }, "credits_spent": { "type": "integer", "description": "Credits charged for successful outputs", "title": "int" }, "deleted_at": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ], "description": "Epoch-millisecond soft-deletion timestamp for the generation job" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Terminal job failure code" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Operator-readable terminal failure message recorded for the job" }, "id": { "type": "string", "description": "Stable identifier of this persisted generation job", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "idempotency_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Caller key used to replay an earlier equivalent generation request" }, "requested_count": { "type": "integer", "description": "Output panels requested for this job", "title": "int" }, "reserved_credits": { "type": "integer", "description": "Credits held for this job", "title": "int" }, "status": { "type": "string", "enum": [ "queued", "processing", "succeeded", "failed", "deleted" ], "description": "Persisted job lifecycle state" }, "system_prompt_version": { "type": "string", "description": "Server-owned prompt revision used to compose this generation" }, "updated_at": { "type": "integer", "description": "Epoch milliseconds of the latest job change", "title": "int" }, "user_id": { "type": "string", "description": "Account that owns the generation job" }, "user_prompt": { "type": "string", "description": "Caller art direction stored with the job" } }, "additionalProperties": false, "description": "Complete D1 generation_jobs row used by generation workflows" }, { "type": "null" } ], "description": "Generation job projection, or null when no job matches the id" }, "outputs": { "type": "array", "items": { "type": "object", "required": [ "byte_size", "content_type", "created_at", "credit_ledger_id", "deleted_at", "error_code", "error_message", "estimated_cost_usd", "id", "job_id", "output_index", "provider_model", "provider_request_id", "r2_key", "status", "usage_json", "user_id" ], "properties": { "byte_size": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ], "description": "Stored image byte length" }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stored image MIME type" }, "created_at": { "type": "integer", "description": "Epoch milliseconds when the output was recorded", "title": "int" }, "credit_ledger_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Associated credit-ledger entry" }, "deleted_at": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ], "description": "Output soft-delete timestamp" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Output failure code" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Output failure message" }, "estimated_cost_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Estimated provider cost in USD retained for pricing remeasurement" }, "id": { "type": "string", "description": "Stable identifier of this generated output" }, "job_id": { "type": "string", "description": "Generation job that owns this output", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "output_index": { "type": "integer", "description": "Zero-based panel position within the job", "title": "int" }, "provider_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Producing image model" }, "provider_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Provider request reference retained for output diagnostics" }, "r2_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Private generated-image R2 key" }, "status": { "type": "string", "enum": [ "succeeded", "failed", "deleted" ], "description": "Persisted output lifecycle state" }, "usage_json": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Raw provider usage JSON" }, "user_id": { "type": "string", "description": "Account that owns the generated output" } }, "additionalProperties": false, "description": "Complete D1 generation_outputs row used by generation workflows" }, "description": "Generated output rows belonging to the looked-up job" } }, "additionalProperties": false, "description": "GET /admin/jobs/:id response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/admin/settings/max-user-prompt-chars": { "post": { "tags": [ "account" ], "operationId": "account.setMaxPromptChars", "parameters": [], "security": [], "responses": { "200": { "description": "POST /admin/settings/max-user-prompt-chars response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "description": "Persisted generation-setting key that was updated" }, "value": { "type": "integer", "description": "New maximum prompt length allowed for one generation request", "title": "int" } }, "additionalProperties": false, "description": "POST /admin/settings/max-user-prompt-chars response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "value" ], "properties": { "value": { "$ref": "#/components/schemas/Int", "description": "Maximum prompt length allowed for one generation request", "title": "between(1, 32000)", "minimum": 1, "maximum": 32000 } }, "additionalProperties": false, "description": "POST /admin/settings/max-user-prompt-chars request body" } } }, "required": true } } }, "/api/v1/assistant/memories": { "post": { "tags": [ "assistant" ], "operationId": "assistant.saveMemory", "parameters": [], "security": [], "responses": { "200": { "description": "POST /api/v1/assistant/memories response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "item" ], "properties": { "item": { "type": "object", "required": [ "id", "kind", "title", "source", "preview", "chunkCount", "createdAt" ], "properties": { "id": { "type": "string", "description": "Logical item id" }, "kind": { "type": "string", "enum": [ "memory", "document", "generation", "note" ], "description": "Item kind" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Title, or null" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Provenance tag, or null" }, "preview": { "type": "string", "description": "Leading slice of the item text" }, "chunkCount": { "$ref": "#/components/schemas/Int", "description": "Number of embedded chunk vectors for this item", "title": "greaterThan(0)", "exclusiveMinimum": 0 }, "createdAt": { "type": "integer", "description": "Creation time, epoch milliseconds", "title": "int" } }, "additionalProperties": false, "description": "The item that was embedded and stored" } }, "additionalProperties": false, "description": "POST /api/v1/assistant/memories response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "Raw text to embed and remember", "title": "minLength(1)", "minLength": 1 }, "kind": { "type": "string", "enum": [ "memory", "document", "generation", "note" ], "description": "Item kind, defaulting to memory" }, "title": { "type": "string" }, "source": { "type": "string" }, "metadata": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "type": "string" }, "description": "Optional string map of caller metadata stored with the item" } }, "additionalProperties": false, "description": "POST /api/v1/assistant/memories request body" } } }, "required": true } }, "get": { "tags": [ "assistant" ], "operationId": "assistant.listMemories", "parameters": [], "security": [], "responses": { "200": { "description": "GET /api/v1/assistant/memories response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "title", "source", "preview", "chunkCount", "createdAt" ], "properties": { "id": { "type": "string", "description": "Logical item id" }, "kind": { "type": "string", "enum": [ "memory", "document", "generation", "note" ], "description": "Item kind" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Title, or null" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Provenance tag, or null" }, "preview": { "type": "string", "description": "Leading slice of the item text" }, "chunkCount": { "$ref": "#/components/schemas/Int", "description": "Number of embedded chunk vectors for this item", "title": "greaterThan(0)", "exclusiveMinimum": 0 }, "createdAt": { "type": "integer", "description": "Creation time, epoch milliseconds", "title": "int" } }, "additionalProperties": false, "description": "A stored assistant item surfaced to its owner" }, "description": "Owned items, newest first" } }, "additionalProperties": false, "description": "GET /api/v1/assistant/memories response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/assistant/memories/{itemId}": { "delete": { "tags": [ "assistant" ], "operationId": "assistant.deleteMemory", "parameters": [ { "name": "itemId", "in": "path", "schema": { "type": "string", "description": "Assistant item id from the route path" }, "required": true, "description": "Assistant item id from the route path" } ], "security": [], "responses": { "200": { "description": "DELETE /api/v1/assistant/memories/{itemId} response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "string", "description": "The deleted logical item id" }, "deleted": { "type": "boolean", "description": "True when at least one chunk was removed" } }, "additionalProperties": false, "description": "DELETE /api/v1/assistant/memories/{itemId} response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/assistant/search": { "post": { "tags": [ "assistant" ], "operationId": "assistant.searchAssistant", "parameters": [], "security": [], "responses": { "200": { "description": "POST /api/v1/assistant/search response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "query", "matches" ], "properties": { "query": { "type": "string", "description": "The query that was searched" }, "matches": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "title", "source", "text", "score", "scope" ], "properties": { "id": { "type": "string", "description": "Logical item id this chunk belongs to" }, "kind": { "type": "string", "enum": [ "memory", "document", "generation", "note" ], "description": "Item kind" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Item title, or null" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Provenance tag, or null" }, "text": { "type": "string", "description": "Matched chunk text to feed into a prompt" }, "score": { "type": "number", "description": "Cosine similarity score in [0, 1]" }, "scope": { "type": "string", "enum": [ "user", "system" ], "description": "Whether the match came from the caller or the shared product-docs corpus" } }, "additionalProperties": false, "description": "One scored retrieval match" }, "description": "Ranked matches, highest score first" } }, "additionalProperties": false, "description": "POST /api/v1/assistant/search response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Natural-language query to embed and match", "title": "minLength(1)", "minLength": 1 }, "topK": { "allOf": [ { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 20", "title": "between(1, 20)", "minimum": 1, "maximum": 20 } ], "description": "Maximum matches to return (1–20), default 8" }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "memory", "document", "generation", "note" ], "description": "Kind of a stored assistant item (memory, document, generation, note)" } }, "includeDocs": { "type": "boolean", "description": "Whether to also search the shared product-docs corpus" } }, "additionalProperties": false, "description": "POST /api/v1/assistant/search request body" } } }, "required": true } } }, "/api/v1/assistant/docs": { "post": { "tags": [ "assistant" ], "operationId": "assistant.ingestDoc", "parameters": [], "security": [], "responses": { "200": { "description": "POST /api/v1/assistant/docs response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "item", "replaced" ], "properties": { "item": { "type": "object", "required": [ "id", "kind", "title", "source", "preview", "chunkCount", "createdAt" ], "properties": { "id": { "type": "string", "description": "Logical item id" }, "kind": { "type": "string", "enum": [ "memory", "document", "generation", "note" ], "description": "Item kind" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Title, or null" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Provenance tag, or null" }, "preview": { "type": "string", "description": "Leading slice of the item text" }, "chunkCount": { "$ref": "#/components/schemas/Int", "description": "Number of embedded chunk vectors for this item", "title": "greaterThan(0)", "exclusiveMinimum": 0 }, "createdAt": { "type": "integer", "description": "Creation time, epoch milliseconds", "title": "int" } }, "additionalProperties": false, "description": "The doc entry embedded into the system corpus" }, "replaced": { "type": "boolean", "description": "True when an existing entry with the same slug was overwritten" } }, "additionalProperties": false, "description": "POST /api/v1/assistant/docs response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "slug", "text" ], "properties": { "slug": { "type": "string", "description": "Stable slug; re-ingesting the same slug replaces this entry", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "title": "maxLength(120)", "maxLength": 120 }, "text": { "type": "string", "description": "Doc body to embed into the system corpus", "title": "minLength(1)", "minLength": 1 }, "title": { "type": "string", "description": "Optional human-readable title shown in listings" }, "source": { "type": "string", "description": "Optional provenance tag (e.g. the doc URL or repo path)" } }, "additionalProperties": false, "description": "POST /api/v1/assistant/docs request body" } } }, "required": true } } }, "/api/v1/demo/listings": { "post": { "tags": [ "demo" ], "operationId": "demo.createDemoListing", "parameters": [], "security": [], "responses": { "200": { "description": "Public-demo listing job status response", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "status", "stage", "stages", "appStoreUrl", "appName", "requestedCount", "succeededCount", "failedCount", "budgetUsdCents", "estimatedCostUsdCents", "remainingBudgetUsdCents", "before", "after", "error", "createdAt", "updatedAt" ], "properties": { "jobId": { "type": "string", "description": "Identifier of the public-demo generation job", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "status": { "type": "string", "enum": [ "queued", "processing", "succeeded", "failed", "deleted" ], "description": "Overall lifecycle state of the public-demo job" }, "stage": { "type": "string", "enum": [ "validate", "pull", "analyze", "budget", "generate", "compose", "done" ], "description": "Furthest active or completed demo pipeline stage" }, "stages": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "status" ], "properties": { "id": { "type": "string", "enum": [ "validate", "pull", "analyze", "budget", "generate", "compose", "done" ], "description": "Stable identifier of the demo pipeline stage" }, "label": { "type": "string", "description": "Human-readable label for the demo stage" }, "status": { "type": "string", "enum": [ "pending", "active", "done", "failed" ], "description": "Current lifecycle state of the demo stage" } }, "additionalProperties": false, "description": "One progress stage in the public-demo pipeline" }, "description": "Ordered progress rows for every demo pipeline stage" }, "appStoreUrl": { "type": "string" }, "appName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "App name extracted from the listing, or null before discovery" }, "requestedCount": { "type": "integer", "description": "Number of generated panels requested for the demo", "title": "int" }, "succeededCount": { "type": "integer", "description": "Number of demo panels generated successfully", "title": "int" }, "failedCount": { "type": "integer", "description": "Number of demo panels that failed to generate", "title": "int" }, "budgetUsdCents": { "type": "number", "enum": [ 1000 ], "description": "Global public-demo budget in US-dollar cents" }, "estimatedCostUsdCents": { "type": "integer", "description": "Estimated cost consumed by this demo job in US-dollar cents", "title": "int" }, "remainingBudgetUsdCents": { "type": "integer", "description": "Unspent global demo budget in US-dollar cents", "title": "int" }, "before": { "type": "array", "items": { "type": "object", "required": [ "index", "url" ], "properties": { "index": { "$ref": "#/components/schemas/Int", "description": "Zero-based position of the source screenshot", "title": "greaterThanOrEqualTo(0)", "minimum": 0 }, "url": { "type": "string", "description": "Public URL of the source screenshot" } }, "additionalProperties": false, "description": "Source App Store screenshot shown before generation" }, "description": "Source App Store screenshots ordered for comparison" }, "after": { "type": "array", "items": { "type": "object", "required": [ "index", "status", "url" ], "properties": { "index": { "$ref": "#/components/schemas/Int", "description": "Zero-based position of the generated panel", "title": "greaterThanOrEqualTo(0)", "minimum": 0 }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed" ], "description": "Generation lifecycle state for this demo panel" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Public URL of the generated panel, or null until available" } }, "additionalProperties": false, "description": "Generated panel shown after the demo completes" }, "description": "Generated demo panels ordered for comparison" }, "error": { "anyOf": [ { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable demo failure code" }, "message": { "type": "string", "description": "Human-readable explanation of the demo failure" } }, "additionalProperties": false, "description": "Public-demo job failure details" }, { "type": "null" } ], "description": "Public-demo job failure details, or null when no error is present" }, "createdAt": { "type": "string", "description": "ISO timestamp when the public-demo job was created" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the public-demo job was last updated" }, "reusedExisting": { "type": "boolean", "description": "Whether an existing demo job was reused for the requester IP" } }, "additionalProperties": false, "description": "Public-demo listing job status response" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "appStoreUrl" ], "properties": { "appStoreUrl": { "type": "string" } }, "additionalProperties": false, "description": "POST /api/v1/demo/listings request body" } } }, "required": true } } }, "/api/v1/demo/listings/{jobId}": { "get": { "tags": [ "demo" ], "operationId": "demo.getDemoListing", "parameters": [ { "name": "jobId", "in": "path", "schema": { "type": "string", "description": "Public-demo generation job id from the path" }, "required": true, "description": "Public-demo generation job id from the path" } ], "security": [], "responses": { "200": { "description": "Public-demo listing job status response", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "status", "stage", "stages", "appStoreUrl", "appName", "requestedCount", "succeededCount", "failedCount", "budgetUsdCents", "estimatedCostUsdCents", "remainingBudgetUsdCents", "before", "after", "error", "createdAt", "updatedAt" ], "properties": { "jobId": { "type": "string", "description": "Identifier of the public-demo generation job", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "status": { "type": "string", "enum": [ "queued", "processing", "succeeded", "failed", "deleted" ], "description": "Overall lifecycle state of the public-demo job" }, "stage": { "type": "string", "enum": [ "validate", "pull", "analyze", "budget", "generate", "compose", "done" ], "description": "Furthest active or completed demo pipeline stage" }, "stages": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "status" ], "properties": { "id": { "type": "string", "enum": [ "validate", "pull", "analyze", "budget", "generate", "compose", "done" ], "description": "Stable identifier of the demo pipeline stage" }, "label": { "type": "string", "description": "Human-readable label for the demo stage" }, "status": { "type": "string", "enum": [ "pending", "active", "done", "failed" ], "description": "Current lifecycle state of the demo stage" } }, "additionalProperties": false, "description": "One progress stage in the public-demo pipeline" }, "description": "Ordered progress rows for every demo pipeline stage" }, "appStoreUrl": { "type": "string" }, "appName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "App name extracted from the listing, or null before discovery" }, "requestedCount": { "type": "integer", "description": "Number of generated panels requested for the demo", "title": "int" }, "succeededCount": { "type": "integer", "description": "Number of demo panels generated successfully", "title": "int" }, "failedCount": { "type": "integer", "description": "Number of demo panels that failed to generate", "title": "int" }, "budgetUsdCents": { "type": "number", "enum": [ 1000 ], "description": "Global public-demo budget in US-dollar cents" }, "estimatedCostUsdCents": { "type": "integer", "description": "Estimated cost consumed by this demo job in US-dollar cents", "title": "int" }, "remainingBudgetUsdCents": { "type": "integer", "description": "Unspent global demo budget in US-dollar cents", "title": "int" }, "before": { "type": "array", "items": { "type": "object", "required": [ "index", "url" ], "properties": { "index": { "$ref": "#/components/schemas/Int", "description": "Zero-based position of the source screenshot", "title": "greaterThanOrEqualTo(0)", "minimum": 0 }, "url": { "type": "string", "description": "Public URL of the source screenshot" } }, "additionalProperties": false, "description": "Source App Store screenshot shown before generation" }, "description": "Source App Store screenshots ordered for comparison" }, "after": { "type": "array", "items": { "type": "object", "required": [ "index", "status", "url" ], "properties": { "index": { "$ref": "#/components/schemas/Int", "description": "Zero-based position of the generated panel", "title": "greaterThanOrEqualTo(0)", "minimum": 0 }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed" ], "description": "Generation lifecycle state for this demo panel" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Public URL of the generated panel, or null until available" } }, "additionalProperties": false, "description": "Generated panel shown after the demo completes" }, "description": "Generated demo panels ordered for comparison" }, "error": { "anyOf": [ { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable demo failure code" }, "message": { "type": "string", "description": "Human-readable explanation of the demo failure" } }, "additionalProperties": false, "description": "Public-demo job failure details" }, { "type": "null" } ], "description": "Public-demo job failure details, or null when no error is present" }, "createdAt": { "type": "string", "description": "ISO timestamp when the public-demo job was created" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the public-demo job was last updated" }, "reusedExisting": { "type": "boolean", "description": "Whether an existing demo job was reused for the requester IP" } }, "additionalProperties": false, "description": "Public-demo listing job status response" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/waitlist": { "post": { "tags": [ "waitlist" ], "operationId": "waitlist.joinWaitlist", "parameters": [], "security": [], "responses": { "200": { "description": "POST /api/waitlist signup response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "alreadyOnList", "referralCode", "referralUrl", "referralCount" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "Always true — signals a successful waitlist signup or replay" }, "alreadyOnList": { "type": "boolean", "description": "Whether this email was already present on the waitlist" }, "referralCode": { "type": "string", "description": "Referral code assigned to the waitlist member" }, "referralUrl": { "type": "string", "description": "Shareable referral URL embedding the assigned referral code" }, "referralCount": { "type": "integer", "description": "Referral count currently credited to the waitlist member", "title": "int" } }, "additionalProperties": false, "description": "POST /api/waitlist signup response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Normalized email address used for account authentication" }, "source": { "type": "string", "description": "Optional acquisition source label supplied with a waitlist signup" }, "ref": { "type": "string", "description": "Optional raw referral code submitted by the new waitlist member" } }, "additionalProperties": false, "description": "Raw public waitlist signup payload with optional attribution context" } } }, "required": true } } }, "/api/waitlist/count": { "get": { "tags": [ "waitlist" ], "operationId": "waitlist.getWaitlistCount", "parameters": [], "security": [], "responses": { "200": { "description": "GET /api/waitlist/count response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "count" ], "properties": { "count": { "type": "integer", "description": "Total count of members currently stored on the waitlist", "title": "int" } }, "additionalProperties": false, "description": "GET /api/waitlist/count response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/waitlist/referral/{code}": { "get": { "tags": [ "waitlist" ], "operationId": "waitlist.lookupReferral", "parameters": [ { "name": "code", "in": "path", "schema": { "type": "string", "description": "Raw referral code from the route path" }, "required": true, "description": "Raw referral code from the route path" } ], "security": [], "responses": { "200": { "description": "GET /api/waitlist/referral/:code response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "exists", "referralCount" ], "properties": { "exists": { "type": "boolean", "description": "Whether the requested referral code exists on the waitlist" }, "referralCount": { "type": "integer", "description": "Number of signups credited to the requested referral code", "title": "int" } }, "additionalProperties": false, "description": "GET /api/waitlist/referral/:code response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/outreach/events": { "post": { "tags": [ "outreach" ], "operationId": "outreach.logOutreachEvent", "parameters": [], "security": [], "responses": { "200": { "description": "POST /api/outreach/events acceptance acknowledgement body", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "Always true — the outreach event was accepted for background logging" } }, "additionalProperties": false, "description": "POST /api/outreach/events acceptance acknowledgement body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "appId", "eventType" ], "properties": { "appId": { "type": "string", "description": "App Store identifier whose outreach page emitted the analytics event" }, "eventType": { "type": "string", "enum": [ "email_open", "preview_open", "page_focus", "page_blur", "image_view", "image_focus", "cta_click", "download_zip", "waitlist_submit", "waitlist_success", "waitlist_error", "time_on_page" ], "description": "Allowed outreach interaction reported by the preview page" }, "eventId": { "type": "string", "description": "Optional client event identifier used to deduplicate outreach telemetry", "title": "maxLength(120)", "minLength": 1, "maxLength": 120 }, "metadata": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" }, "description": "Optional arbitrary context recorded alongside the outreach event" } }, "additionalProperties": false, "description": "Validated analytics event payload reported by the outreach preview page" } } }, "required": true } } }, "/o/{appId}/open.png": { "get": { "tags": [ "outreach" ], "operationId": "outreach.getOutreachOpenPixel", "parameters": [ { "name": "appId", "in": "path", "schema": { "type": "string", "description": "Raw App Store identifier from the open-pixel route path" }, "required": true, "description": "Raw App Store identifier from the open-pixel route path" } ], "security": [], "responses": { "200": { "description": "Success", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/o/{appId}/{slug}": { "get": { "tags": [ "outreach" ], "operationId": "outreach.getOutreachPreview", "parameters": [ { "name": "appId", "in": "path", "schema": { "type": "string", "description": "Raw App Store identifier from the preview route path" }, "required": true, "description": "Raw App Store identifier from the preview route path" }, { "name": "slug", "in": "path", "schema": { "type": "string", "description": "Raw app slug from the preview route path (normalized by the handler)" }, "required": true, "description": "Raw app slug from the preview route path (normalized by the handler)" } ], "security": [], "responses": { "200": { "description": "a string", "content": { "text/html; charset=utf-8": { "schema": { "type": "string" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/assets/*": { "get": { "tags": [ "outreach" ], "operationId": "outreach.getOutreachAsset", "parameters": [], "security": [], "responses": { "200": { "description": "Success", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/health": { "get": { "tags": [ "health" ], "operationId": "health.getHealth", "parameters": [], "security": [], "responses": { "200": { "description": "GET /api/health probe response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "db" ], "properties": { "ok": { "type": "boolean", "description": "Whether the worker considers itself healthy (database reachable)" }, "db": { "type": "string", "enum": [ "connected", "disconnected" ], "description": "Database connectivity state from the SELECT 1 probe" } }, "additionalProperties": false, "description": "GET /api/health probe response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } }, "/api/v1/status": { "get": { "tags": [ "status" ], "operationId": "status.getStatus", "parameters": [], "security": [], "responses": { "200": { "description": "GET /api/v1/status response body", "content": { "application/json": { "schema": { "type": "object", "required": [ "overall", "updatedAt", "windowDays", "components", "incidents" ], "properties": { "overall": { "type": "string", "enum": [ "operational", "degraded", "partial_outage", "major_outage", "maintenance" ], "description": "Overall system indicator for the status banner" }, "updatedAt": { "type": "integer", "description": "Epoch milliseconds when this report was last updated", "title": "int" }, "windowDays": { "type": "integer", "description": "Number of days of recorded history this report window covers", "title": "int" }, "components": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "description", "state", "detail", "latencyMs", "uptime90dPct", "days" ], "properties": { "id": { "type": "string", "enum": [ "api", "database", "generation", "assets", "email", "website" ], "description": "Identifier of the monitored component" }, "name": { "type": "string", "description": "Human-readable component name shown to readers" }, "description": { "type": "string", "description": "Plain-language summary of what this component covers" }, "state": { "type": "string", "enum": [ "operational", "degraded", "down", "maintenance" ], "description": "Current live-probed component state" }, "detail": { "type": "string", "description": "Human-readable detail of what the probe actually verified" }, "latencyMs": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ], "description": "Most recent probe latency in milliseconds, or null when not measured" }, "uptime90dPct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Recorded uptime percentage across the history window, or null when no samples exist" }, "days": { "type": "array", "items": { "type": "object", "required": [ "day", "state", "uptimePct" ], "properties": { "day": { "type": "string", "description": "UTC calendar day 'YYYY-MM-DD' this uptime bucket covers" }, "state": { "type": "string", "enum": [ "operational", "degraded", "down", "maintenance" ], "description": "Worst component state observed during the day" }, "uptimePct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Measured uptime percentage (0-100) for the day, or null when no samples exist" } }, "additionalProperties": false, "description": "One day of recorded component uptime for the history strip" }, "description": "Per-day uptime buckets oldest-first across the history window" } }, "additionalProperties": false, "description": "Live status plus recorded history for one component" }, "description": "Monitored components in display order" }, "incidents": { "type": "array", "items": { "type": "object", "required": [ "id", "componentId", "impact", "startedAt", "resolvedAt", "detail" ], "properties": { "id": { "type": "string", "description": "Stable incident identifier" }, "componentId": { "type": "string", "enum": [ "api", "database", "generation", "assets", "email", "website" ], "description": "Component the incident affected" }, "impact": { "type": "string", "enum": [ "operational", "degraded", "down", "maintenance" ], "description": "Impact level: worst component state reached during the incident" }, "startedAt": { "type": "integer", "description": "Epoch milliseconds when the incident started", "title": "int" }, "resolvedAt": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ], "description": "Epoch milliseconds when the incident resolved, or null while ongoing" }, "detail": { "type": "string", "description": "Human-readable incident detail carried from the probe" } }, "additionalProperties": false, "description": "One incident auto-derived from recorded downtime" }, "description": "Recent incidents newest-first across the history window" } }, "additionalProperties": false, "description": "GET /api/v1/status response body" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpApiDecodeError" } } } }, "500": { "description": "Stable { error, message, ...extra } worker error body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code surfaced as the { error } field" }, "message": { "type": "string", "description": "Human-readable explanation surfaced as the { message } field" } }, "additionalProperties": false, "description": "Stable { error, message, ...extra } worker error body" } } } } } } } }, "components": { "schemas": { "HttpApiDecodeError": { "type": "object", "required": [ "issues", "message", "_tag" ], "properties": { "issues": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" } }, "message": { "type": "string" }, "_tag": { "type": "string", "enum": [ "HttpApiDecodeError" ] } }, "additionalProperties": false, "description": "The request did not match the expected schema" }, "Issue": { "type": "object", "required": [ "_tag", "path", "message" ], "properties": { "_tag": { "type": "string", "enum": [ "Pointer", "Unexpected", "Missing", "Composite", "Refinement", "Transformation", "Type", "Forbidden" ], "description": "The tag identifying the type of parse issue" }, "path": { "type": "array", "items": { "$ref": "#/components/schemas/PropertyKey" }, "description": "The path to the property where the issue occurred" }, "message": { "type": "string", "description": "A descriptive message explaining the issue" } }, "additionalProperties": false, "description": "Represents an error encountered while parsing a value to match the schema" }, "PropertyKey": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "object", "required": [ "_tag", "key" ], "properties": { "_tag": { "type": "string", "enum": [ "symbol" ] }, "key": { "type": "string" } }, "additionalProperties": false, "description": "an object to be decoded into a globally shared symbol" } ] }, "Int": { "type": "integer", "description": "an integer", "title": "int" } }, "securitySchemes": {} }, "security": [], "tags": [ { "name": "billing" }, { "name": "generation" }, { "name": "auth" }, { "name": "account" }, { "name": "assistant" }, { "name": "demo" }, { "name": "waitlist" }, { "name": "outreach" }, { "name": "health" }, { "name": "status" } ] }