{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "KonfigurátorSPZ API", "version": "1.0.0-beta", "description": "Developer REST API, autonomous onboarding, and MCP. Verification and registry availability are advisory and do not replace approval by the competent Czech authority.", "termsOfService": "https://spz-gen-pr61.dokploy.martinmachava.com/developers/terms", "contact": { "url": "https://spz-gen-pr61.dokploy.martinmachava.com/developers/docs" } }, "servers": [ { "url": "https://spz-gen-pr61.dokploy.martinmachava.com" } ], "externalDocs": { "description": "Agent integration guide", "url": "https://spz-gen-pr61.dokploy.martinmachava.com/developers/agent.md" }, "tags": [ { "name": "Plates", "description": "Metered rendering and advisory evaluation." }, { "name": "Access", "description": "Browser access and account usage." }, { "name": "Operations", "description": "Owned asynchronous operations and artifacts." }, { "name": "Onboarding", "description": "Short-lived autonomous evaluation, domain control, and authenticated human claim." }, { "name": "MCP", "description": "Streamable HTTP MCP transport over the same onboarding authorities." } ], "paths": { "/api/v1/agent-authority/terms": { "get": { "tags": [ "Onboarding" ], "x-konfiguratorspz-status": "available", "security": [], "description": "Scoped delegated authority. Credentials are JSON-body-only, never URL parameters or bearer API keys. No purchase authority. No-store responses.", "operationId": "getDelegatedTerms", "summary": "Retrieve canonical terms and explicit delegate attestation", "responses": { "200": { "description": "Exact canonical terms, version, SHA-256, sections, canonicalization, and delegateAttestation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "version", "canonicalDocumentVersion", "documentSha256", "sections", "delegateAttestation" ], "properties": { "version": { "type": "string" }, "canonicalDocumentVersion": { "type": "string" }, "documentSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "heading": { "type": "string" }, "paragraphs": { "type": "array", "items": { "type": "string" } } } } }, "delegateAttestation": { "type": "string" } } } } } } } } }, "/api/v1/agent-authority/accept": { "post": { "tags": [ "Onboarding" ], "x-konfiguratorspz-status": "available", "security": [], "description": "Scoped delegated authority. Credentials are JSON-body-only, never URL parameters or bearer API keys. No purchase authority. No-store responses.", "operationId": "acceptDelegatedTerms", "summary": "Explicitly accept exact terms on the accountable principal's behalf", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "capability", "termsVersion", "documentSha256", "attestation" ], "properties": { "capability": { "type": "string", "minLength": 1, "maxLength": 256, "writeOnly": true }, "termsVersion": { "type": "string" }, "documentSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "attestation": { "type": "string", "description": "Exact delegateAttestation from terms retrieval." } } } } } }, "responses": { "200": { "description": "Immutable delegated acceptance recorded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "accepted", "authorityId", "principalUserId", "accountId", "actorType", "termsVersion", "documentSha256" ], "properties": { "accepted": { "const": true }, "authorityId": { "type": "string", "format": "uuid" }, "principalUserId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "actorType": { "const": "delegate" }, "termsVersion": { "type": "string" }, "documentSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } } }, "400": { "description": "Invalid JSON or URL query parameters." }, "401": { "description": "Missing, expired, or revoked capability." }, "403": { "description": "Wrong scope, current owner/admin membership, or principal acceptance missing." }, "404": { "description": "Wrong authorized trial or separate claim bearer." }, "409": { "description": "Already used/claimed or exact authorized terms changed/mismatched; secrets never repeated." }, "410": { "description": "Trial expired." }, "413": { "description": "JSON body exceeds 8192 bytes." }, "415": { "description": "Content-Type must be application/json." }, "422": { "description": "Strict request schema or explicit attestation/authorization not satisfied." } } } }, "/api/v1/agent-authority/claim": { "post": { "tags": [ "Onboarding" ], "x-konfiguratorspz-status": "available", "security": [], "description": "Scoped delegated authority. Credentials are JSON-body-only, never URL parameters or bearer API keys. No purchase authority. No-store responses.", "operationId": "claimDelegatedTrial", "summary": "Claim only the authorized trial using a separate claim bearer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "capability", "claimSecret" ], "properties": { "capability": { "type": "string", "minLength": 1, "maxLength": 256, "writeOnly": true }, "claimSecret": { "type": "string", "pattern": "^[a-f0-9]{64}$", "writeOnly": true } } } } } }, "responses": { "200": { "description": "Claimed; rotated key returned once. Read-only unless explicitly scoped/budgeted, expires with authority. Preclaim keys and sessions revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "claimed", "accountId", "projectId", "principalUserId", "authorityId", "apiKey" ], "properties": { "claimed": { "const": true }, "accountId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "principalUserId": { "type": "string", "format": "uuid" }, "authorityId": { "type": "string", "format": "uuid" }, "apiKey": { "type": "string", "readOnly": true } } } } } }, "400": { "description": "Invalid JSON or URL query parameters." }, "401": { "description": "Missing, expired, or revoked capability." }, "403": { "description": "Wrong scope, current owner/admin membership, or principal acceptance missing." }, "404": { "description": "Wrong authorized trial or separate claim bearer." }, "409": { "description": "Already used/claimed or exact authorized terms changed/mismatched; secrets never repeated." }, "410": { "description": "Trial expired." }, "413": { "description": "JSON body exceeds 8192 bytes." }, "415": { "description": "Content-Type must be application/json." }, "422": { "description": "Strict request schema or explicit attestation/authorization not satisfied." } } } }, "/api/v1/agent-authority/authorizations": { "get": { "tags": [ "Onboarding" ], "security": [ { "HumanSession": [] } ], "operationId": "listAgentAuthorities", "summary": "Get authenticated owner authorization contract, CSRF token and latest 100 records", "responses": { "200": { "description": "csrf, accountId, principalUserId, authorization, spendingAuthorization and authorities (never capability)." }, "302": { "description": "Authenticate with Clerk." }, "403": { "description": "Owner/admin required." } } }, "post": { "tags": [ "Onboarding" ], "security": [ { "HumanSession": [] } ], "operationId": "manageAgentAuthority", "summary": "Issue or revoke bounded authority as authenticated owner/admin", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for issue intent; reuse for retries. Replay returns capability null." }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact public site origin." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "intent", "authorization" ], "properties": { "intent": { "const": "issue" }, "authorization": { "type": "object", "additionalProperties": false, "required": [ "trialId", "agentName", "scopes", "expiresInSeconds", "authorization", "termsVersion", "documentSha256" ], "properties": { "termsVersion": { "type": "string" }, "documentSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "trialId": { "type": "string", "format": "uuid" }, "agentName": { "type": "string", "minLength": 1, "maxLength": 120 }, "scopes": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "enum": [ "terms:accept", "trial:claim" ] } }, "expiresInSeconds": { "type": "integer", "minimum": 1, "maximum": 3600 }, "authorization": { "type": "string", "description": "Exact authorization statement from management GET." }, "operationScopes": { "type": "array", "maxItems": 3, "uniqueItems": true, "items": { "enum": [ "generate", "verify", "availability" ] } }, "monthlyCreditBudget": { "type": "integer", "minimum": 0, "maximum": 10000 }, "spendingAuthorization": { "type": "string", "description": "Exact spendingAuthorization from GET; required with operationScopes and monthlyCreditBudget, and requires trial:claim scope." } } } } }, { "type": "object", "additionalProperties": false, "required": [ "intent", "authorityId" ], "properties": { "intent": { "const": "revoke" }, "authorityId": { "type": "string", "format": "uuid" } } } ] } } } }, "responses": { "200": { "description": "Idempotent grant replay or revocation (issued operation key also revoked).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "id", "capability", "replayed", "principal", "accountId", "trialId", "scopes", "expiresAt", "termsVersion", "documentSha256" ], "properties": { "id": { "type": "string", "format": "uuid" }, "capability": { "type": [ "string", "null" ], "readOnly": true }, "replayed": { "type": "boolean" }, "principal": { "type": "object", "required": [ "userId", "displayName", "email" ], "properties": { "userId": { "type": "string", "format": "uuid" }, "displayName": { "type": [ "string", "null" ] }, "email": { "type": "string" } } }, "accountId": { "type": "string", "format": "uuid" }, "trialId": { "type": "string", "format": "uuid" }, "scopes": { "type": "array", "items": { "enum": [ "terms:accept", "trial:claim" ] } }, "expiresAt": { "type": "string", "format": "date-time" }, "termsVersion": { "type": "string" }, "documentSha256": { "type": "string" } } }, { "type": "object", "required": [ "id", "revoked" ], "properties": { "id": { "type": "string", "format": "uuid" }, "revoked": { "const": true } } } ] } } } }, "201": { "description": "Authority metadata and capability once; an idempotent replay has capability null and replayed true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "capability", "replayed", "principal", "accountId", "trialId", "scopes", "expiresAt", "termsVersion", "documentSha256" ], "properties": { "id": { "type": "string", "format": "uuid" }, "capability": { "type": [ "string", "null" ], "readOnly": true }, "replayed": { "type": "boolean" }, "principal": { "type": "object", "required": [ "userId", "displayName", "email" ], "properties": { "userId": { "type": "string", "format": "uuid" }, "displayName": { "type": [ "string", "null" ] }, "email": { "type": "string" } } }, "accountId": { "type": "string", "format": "uuid" }, "trialId": { "type": "string", "format": "uuid" }, "scopes": { "type": "array", "items": { "enum": [ "terms:accept", "trial:claim" ] } }, "expiresAt": { "type": "string", "format": "date-time" }, "termsVersion": { "type": "string" }, "documentSha256": { "type": "string" } } } } } }, "302": { "description": "Authenticate with Clerk." }, "400": { "description": "Invalid JSON or URL query parameters." }, "401": { "description": "Missing, expired, or revoked capability." }, "403": { "description": "Wrong scope, current owner/admin membership, or principal acceptance missing." }, "404": { "description": "Wrong authorized trial or separate claim bearer." }, "409": { "description": "Already used/claimed or exact authorized terms changed/mismatched; secrets never repeated." }, "410": { "description": "Trial expired." }, "413": { "description": "JSON body exceeds 8192 bytes." }, "415": { "description": "Content-Type must be application/json." }, "422": { "description": "Strict request schema or explicit attestation/authorization not satisfied." } } } }, "/api/v1/plates/generate": { "post": { "x-konfiguratorspz-status": "available", "tags": [ "Plates" ], "operationId": "generatePlate", "summary": "Queue a plate PNG generation", "description": "Accepts renderable text. A rendered result is not a statement of legal validity or availability.", "security": [ { "DeveloperBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable key for this semantic operation; reuse it for transport retries. A completed operation replays its terminal 200 success or safe 500 failure response.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneratePlateRequest" } } } }, "responses": { "200": { "description": "Idempotent replay of a successfully completed operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationResult" } } } }, "202": { "description": "Operation queued, including an idempotent replay while the original operation is still nonterminal.", "headers": { "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedOperation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge32KiB" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/TerminalFailure" } } } }, "/api/v1/plates/verify": { "post": { "x-konfiguratorspz-status": "available", "tags": [ "Plates" ], "operationId": "verifyPlate", "summary": "Queue an advisory plate-rule evaluation", "description": "Evaluates supported renderer and Czech registration-mark rules without reserving a mark.", "security": [ { "DeveloperBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable key for this semantic operation; reuse it for transport retries. A completed operation replays its terminal 200 success or safe 500 failure response.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlateTextRequest" } } } }, "responses": { "200": { "description": "Idempotent replay of a successfully completed operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResult" } } } }, "202": { "description": "Operation queued, including an idempotent replay while the original operation is still nonterminal.", "headers": { "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedOperation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge32KiB" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/TerminalFailure" } } } }, "/api/v1/plates/availability": { "post": { "x-konfiguratorspz-status": "available", "tags": [ "Plates" ], "operationId": "checkPlateAvailability", "summary": "Queue an advisory registry-snapshot lookup", "description": "Requires legally valid official text. A not-found result neither reserves a mark nor guarantees administrative approval.", "security": [ { "DeveloperBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable key for this semantic operation; reuse it for transport retries. A completed operation replays its terminal 200 success or safe 500 failure response.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlateTextRequest" } } } }, "responses": { "200": { "description": "Idempotent replay of a successfully completed operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityResult" } } } }, "202": { "description": "Operation queued, including an idempotent replay while the original operation is still nonterminal.", "headers": { "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedOperation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge32KiB" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/TerminalFailure" } } } }, "/api/v1/browser-sessions": { "post": { "x-konfiguratorspz-status": "available", "tags": [ "Access" ], "operationId": "createBrowserSession", "summary": "Create an origin-bound browser session", "description": "Server-only. The exact origin must be on the project allowlist.", "security": [ { "DeveloperBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSessionRequest" } } } }, "responses": { "201": { "description": "Browser session created. The returned credential is short-lived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/PayloadTooLarge32KiB" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/pricing": { "get": { "x-konfiguratorspz-status": "available", "tags": [ "Access" ], "operationId": "getPricing", "summary": "Read provisional public pricing and fallback policy", "security": [], "responses": { "200": { "description": "Current provisional pricing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pricing" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/usage": { "get": { "x-konfiguratorspz-status": "available", "tags": [ "Access" ], "operationId": "getUsage", "summary": "Read paginated project usage aggregates", "security": [ { "DeveloperBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage rows and an optional next cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsagePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/operations/{id}": { "get": { "x-konfiguratorspz-status": "available", "tags": [ "Operations" ], "operationId": "getOperation", "summary": "Read an owned operation", "security": [ { "DeveloperBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "200": { "description": "Owned operation state and result when complete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/artifacts/{id}": { "get": { "x-konfiguratorspz-status": "available", "tags": [ "Operations" ], "operationId": "getArtifact", "summary": "Retrieve an owned generated PNG", "security": [ { "DeveloperBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "200": { "description": "PNG artifact. Validate the Digest header when persisting it.", "headers": { "Digest": { "schema": { "type": "string" } }, "X-Artifact-Expires-At": { "schema": { "type": "string", "format": "date-time" } } }, "content": { "image/png": { "schema": { "type": "string", "contentEncoding": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/agent-trials": { "post": { "x-konfiguratorspz-status": "available", "tags": [ "Onboarding" ], "operationId": "createAgentTrial", "summary": "Create a bounded evaluation trial", "description": "Creates a short-lived, scoped, metered, provider-attributed principal. The secret is returned only on first issuance; an idempotent replay returns apiKey null and secretReturned false.", "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable key for this semantic operation; reuse it for transport retries. A completed operation replays its terminal 200 success or safe 500 failure response.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "200": { "description": "Idempotent replay; the API-key secret is not returned again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTrial" } } } }, "201": { "description": "New trial issued; copy the API key now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTrial" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge4KiB" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/agent-trials/domain-challenges": { "post": { "x-konfiguratorspz-status": "available", "tags": [ "Onboarding" ], "operationId": "createDomainChallenge", "summary": "Create an HTTPS domain-control challenge", "description": "Requires an active evaluation principal owned by the authenticated server API key.", "security": [ { "DeveloperBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainChallengeRequest" } } } }, "responses": { "201": { "description": "Challenge created. Publish exactly the returned hostname and challenge fields at the returned URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainChallengeCreated" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/PayloadTooLarge4KiB" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/agent-trials/domain-challenges/{id}": { "get": { "x-konfiguratorspz-status": "available", "tags": [ "Onboarding" ], "operationId": "getDomainChallenge", "summary": "Read an owned challenge", "security": [ { "DeveloperBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/ChallengeId" } ], "responses": { "200": { "description": "Current challenge state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainChallenge" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/agent-trials/domain-challenges/{id}/verify": { "post": { "x-konfiguratorspz-status": "available", "tags": [ "Onboarding" ], "operationId": "verifyDomainChallenge", "summary": "Verify an exact HTTPS domain-control response", "description": "Fetches only the issued HTTPS /.well-known/konfiguratorspz.json path under bounded DNS, redirect, response-size, and deadline policy.", "security": [ { "DeveloperBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/ChallengeId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "200": { "description": "Verified promotion state. Replays do not duplicate promotional credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainChallengeVerification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "413": { "$ref": "#/components/responses/PayloadTooLarge4KiB" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/developers/claim/{handle}": { "get": { "x-konfiguratorspz-status": "available", "tags": [ "Onboarding" ], "operationId": "openHumanClaim", "summary": "Open the authenticated human claim handoff", "description": "Browser flow requiring Clerk authentication. Claim submission also requires current developer-terms acceptance and CSRF validation, then revokes the evaluation key and returns a replacement once.", "security": [ { "HumanSession": [] } ], "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "responses": { "200": { "description": "Authenticated claim page.", "content": { "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "Claim handle not found." } } }, "post": { "x-konfiguratorspz-status": "available", "tags": [ "Onboarding" ], "operationId": "claimAgentTrial", "summary": "Claim an evaluation project and rotate its key", "description": "Authenticated browser form mutation. Requires the CSRF value issued by the claim-page loader and current developer-terms acceptance. The replacement API key is returned once; a replay returns apiKey null.", "security": [ { "HumanSession": [] } ], "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "additionalProperties": false, "required": [ "csrf", "termsVersion", "documentSha256" ], "properties": { "csrf": { "type": "string", "minLength": 1 }, "termsVersion": { "type": "string", "minLength": 1 }, "documentSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } } }, "responses": { "200": { "description": "Claim result. A newly rotated API key is exposed only on the first successful claim.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTrialClaim" } } } }, "400": { "description": "Malformed browser form; no claim or credential rotation occurred." }, "403": { "description": "Authentication, ownership, or current terms requirements were not satisfied." }, "404": { "description": "Claim handle not found." }, "409": { "description": "The selected account or displayed legal document is stale (reload required), or the evaluation was already claimed by a different human." }, "410": { "description": "Claim handle expired." } } } }, "/mcp": { "post": { "x-konfiguratorspz-status": "available", "tags": [ "MCP" ], "operationId": "mcpStreamableHttp", "summary": "Call the MCP Streamable HTTP endpoint", "description": "Supports stateless protocol 2026-07-28 and initialization-based 2025-06-18 compatibility. Accept must include application/json and text/event-stream. create_agent_trial is public; domain-challenge tools require DeveloperBearer in the HTTP Authorization header and reject credentials in JSON-RPC arguments. Deprecated HTTP+SSE is not supported.", "security": [ {}, { "DeveloperBearer": [] } ], "parameters": [ { "name": "MCP-Protocol-Version", "in": "header", "required": false, "description": "2026-07-28 for current stateless requests or 2025-06-18 after legacy initialization. Headerless initialize is accepted for compatibility.", "schema": { "type": "string", "enum": [ "2026-07-28", "2025-06-18" ] } }, { "name": "MCP-Session-Id", "in": "header", "required": false, "description": "Required after a legacy initialize response; not used by current stateless requests.", "schema": { "type": "string" } }, { "name": "MCP-Method", "in": "header", "required": false, "description": "Required for current stateless requests and must exactly mirror the JSON-RPC method.", "schema": { "type": "string" } }, { "name": "MCP-Name", "in": "header", "required": false, "description": "Required for current tools/call and must mirror params.name; omit for other methods.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" } } } }, "responses": { "200": { "description": "JSON-RPC success, tool result, or protocol error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } }, "202": { "description": "Accepted legacy initialization notification without a response body." }, "400": { "description": "Invalid JSON-RPC request, protocol metadata, or mirrored headers." }, "403": { "description": "Origin does not match the configured canonical origin." }, "405": { "description": "Method not allowed." }, "406": { "description": "Accept does not include both required response media types." }, "413": { "description": "Request body exceeds 65536 bytes." }, "415": { "description": "Content-Type is not application/json." }, "429": { "description": "Legacy initialize capacity or per-caller admission limit exhausted. The body remains a JSON-RPC error response; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpLegacyAdmissionErrorResponse" } } } }, "503": { "description": "Canonical public origin is unavailable or invalid." } } }, "delete": { "x-konfiguratorspz-status": "available", "tags": [ "MCP" ], "operationId": "deleteLegacyMcpSession", "summary": "Terminate a legacy MCP session", "description": "Requires MCP-Protocol-Version 2025-06-18 and the exact MCP-Session-Id returned by initialize. Current stateless requests have no session to delete.", "security": [ {}, { "DeveloperBearer": [] } ], "parameters": [ { "name": "MCP-Protocol-Version", "in": "header", "required": true, "schema": { "const": "2025-06-18" } }, { "name": "MCP-Session-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Legacy session deleted." }, "400": { "description": "Legacy protocol version or session identifier is missing or invalid." }, "403": { "description": "Origin does not match the configured canonical origin." }, "404": { "description": "Legacy session not found." }, "503": { "description": "Canonical public origin is unavailable or invalid." } } } } }, "components": { "securitySchemes": { "DeveloperBearer": { "type": "http", "scheme": "bearer", "description": "Project API key for server calls or an origin-bound browser session where permitted." }, "HumanSession": { "type": "apiKey", "in": "cookie", "name": "__session", "description": "Clerk-authenticated human browser session; not an agent credential." } }, "parameters": { "ResourceId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "ChallengeId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } }, "schemas": { "EmptyObject": { "type": "object", "additionalProperties": false, "maxProperties": 0 }, "AgentTrial": { "type": "object", "additionalProperties": false, "required": [ "trialId", "projectId", "apiKey", "secretReturned", "scopes", "expiresAt", "credits", "attribution", "replayed" ], "properties": { "trialId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "apiKey": { "type": [ "string", "null" ], "readOnly": true, "description": "Returned only for a new issuance; null on replay." }, "secretReturned": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "generate", "verify", "artifacts" ] } }, "expiresAt": { "type": "string", "format": "date-time" }, "credits": { "type": "integer", "minimum": 1 }, "attribution": { "const": "provider" }, "claimUrl": { "type": "string", "format": "uri", "readOnly": true, "description": "One-time claim bearer returned only with a new issuance. Omitted on idempotency replay; recover it only from an authenticated human claim flow or an authorized server API-key exhaustion response." }, "replayed": { "type": "boolean" } } }, "DomainChallengeRequest": { "type": "object", "additionalProperties": false, "required": [ "hostname" ], "properties": { "hostname": { "type": "string", "minLength": 1, "maxLength": 253 } } }, "DomainChallenge": { "type": "object", "additionalProperties": false, "required": [ "id", "hostname", "url", "expiresAt", "status", "verifiedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "hostname": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "pending", "verified", "expired" ] }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "DomainChallengeCreated": { "type": "object", "additionalProperties": false, "required": [ "id", "hostname", "url", "challenge", "expiresAt", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "hostname": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "challenge": { "type": "string", "readOnly": true }, "expiresAt": { "type": "string", "format": "date-time" }, "status": { "const": "pending" } } }, "DomainChallengeVerification": { "type": "object", "additionalProperties": false, "required": [ "id", "hostname", "origin", "status", "promotionalCreditsGranted" ], "properties": { "id": { "type": "string", "format": "uuid" }, "hostname": { "type": "string" }, "origin": { "type": "string", "format": "uri" }, "status": { "const": "verified" }, "promotionalCreditsGranted": { "type": "boolean" } } }, "JsonRpcRequest": { "anyOf": [ { "$ref": "#/components/schemas/McpCurrentRequest" }, { "$ref": "#/components/schemas/McpLegacyRequest" } ] }, "McpCurrentRequest": { "oneOf": [ { "$ref": "#/components/schemas/McpCurrentDiscoverRequest" }, { "$ref": "#/components/schemas/McpCurrentToolsListRequest" }, { "$ref": "#/components/schemas/McpCurrentToolsCallRequest" } ] }, "McpLegacyRequest": { "oneOf": [ { "$ref": "#/components/schemas/McpInitializeRequest" }, { "$ref": "#/components/schemas/McpInitializedNotification" }, { "$ref": "#/components/schemas/McpLegacyToolsListRequest" }, { "$ref": "#/components/schemas/McpLegacyToolsCallRequest" } ] }, "McpCurrentDiscoverRequest": { "type": "object", "additionalProperties": false, "required": [ "jsonrpc", "id", "method", "params" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "const": "server/discover" }, "params": { "type": "object", "additionalProperties": false, "required": [ "_meta" ], "properties": { "_meta": { "$ref": "#/components/schemas/McpCurrentMetadata" } } } } }, "McpCurrentToolsListRequest": { "type": "object", "additionalProperties": false, "required": [ "jsonrpc", "id", "method", "params" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "const": "tools/list" }, "params": { "type": "object", "additionalProperties": false, "required": [ "_meta" ], "properties": { "_meta": { "$ref": "#/components/schemas/McpCurrentMetadata" }, "cursor": { "type": "string" } } } } }, "McpCurrentToolsCallRequest": { "type": "object", "additionalProperties": false, "required": [ "jsonrpc", "id", "method", "params" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "const": "tools/call" }, "params": { "type": "object", "additionalProperties": false, "required": [ "_meta", "name" ], "properties": { "_meta": { "$ref": "#/components/schemas/McpCurrentMetadata" }, "name": { "type": "string", "minLength": 1 }, "arguments": { "type": "object", "additionalProperties": true }, "requestState": { "type": "string" }, "inputResponses": { "type": "object", "additionalProperties": true } } } } }, "McpCurrentMetadata": { "type": "object", "required": [ "io.modelcontextprotocol/protocolVersion", "io.modelcontextprotocol/clientCapabilities" ], "properties": { "io.modelcontextprotocol/protocolVersion": { "const": "2026-07-28" }, "io.modelcontextprotocol/clientCapabilities": { "type": "object", "additionalProperties": true }, "io.modelcontextprotocol/clientInfo": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "McpInitializeRequest": { "type": "object", "additionalProperties": false, "required": [ "jsonrpc", "id", "method", "params" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "const": "initialize" }, "params": { "type": "object", "additionalProperties": false, "required": [ "protocolVersion", "capabilities", "clientInfo" ], "properties": { "protocolVersion": { "type": "string" }, "capabilities": { "type": "object", "additionalProperties": true }, "clientInfo": { "type": "object", "additionalProperties": true }, "_meta": { "type": "object", "additionalProperties": true } } } } }, "McpInitializedNotification": { "type": "object", "additionalProperties": false, "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "const": "2.0" }, "method": { "const": "notifications/initialized" }, "params": { "type": "object", "properties": { "_meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } }, "McpLegacyToolsListRequest": { "type": "object", "additionalProperties": false, "required": [ "jsonrpc", "id", "method" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "const": "tools/list" }, "params": { "type": "object", "additionalProperties": false, "properties": { "_meta": { "type": "object", "additionalProperties": true }, "cursor": { "type": "string" } } } } }, "McpLegacyToolsCallRequest": { "type": "object", "additionalProperties": false, "required": [ "jsonrpc", "id", "method", "params" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "const": "tools/call" }, "params": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "_meta": { "type": "object", "additionalProperties": true }, "name": { "type": "string", "minLength": 1 }, "arguments": { "type": "object", "additionalProperties": true } } } } }, "JsonRpcSuccessResponse": { "type": "object", "additionalProperties": false, "required": [ "jsonrpc", "id", "result" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "result": { "type": "object", "additionalProperties": true } } }, "JsonRpcErrorResponse": { "type": "object", "additionalProperties": false, "required": [ "jsonrpc", "id", "error" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer", "null" ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": {} } } } }, "McpLegacyAdmissionErrorResponse": { "type": "object", "additionalProperties": false, "required": [ "jsonrpc", "id", "error" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "data" ], "properties": { "code": { "const": -32000 }, "message": { "enum": [ "Legacy MCP session capacity exhausted", "Legacy MCP initialization rate limit exceeded" ] }, "data": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "enum": [ "capacity", "rate_limit" ] } } } } } } }, "JsonRpcResponse": { "oneOf": [ { "$ref": "#/components/schemas/JsonRpcSuccessResponse" }, { "$ref": "#/components/schemas/JsonRpcErrorResponse" } ] }, "AgentTrialClaim": { "type": "object", "additionalProperties": false, "required": [ "projectId", "accountId", "claimed", "apiKey" ], "properties": { "projectId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "claimed": { "type": "boolean" }, "apiKey": { "type": [ "string", "null" ], "readOnly": true } } }, "PlateShape": { "type": "string", "enum": [ "standard", "carrier", "truck", "van-square", "square", "motorbike", "moped" ] }, "PlateTextRequest": { "type": "object", "additionalProperties": false, "required": [ "shape", "text" ], "properties": { "shape": { "$ref": "#/components/schemas/PlateShape" }, "text": { "type": "string", "maxLength": 256 } } }, "PlateColors": { "type": "object", "additionalProperties": false, "properties": { "barColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "bgColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "textColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "borderColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "euStarColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "czColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } } }, "GeneratePlateRequest": { "type": "object", "additionalProperties": false, "required": [ "shape", "text" ], "properties": { "shape": { "$ref": "#/components/schemas/PlateShape" }, "text": { "type": "string", "description": "Renderable uppercase text; capacity depends on shape." }, "colors": { "$ref": "#/components/schemas/PlateColors" }, "branding": { "type": "string", "enum": [ "provider", "custom", "none" ] } } }, "BrowserSessionRequest": { "type": "object", "additionalProperties": false, "required": [ "origin", "scopes" ], "properties": { "origin": { "type": "string", "format": "uri", "description": "Exact allowed origin, without a path." }, "scopes": { "type": "array", "minItems": 1, "maxItems": 4, "uniqueItems": true, "items": { "type": "string", "enum": [ "generate", "verify", "availability", "artifacts" ] } }, "ttlSeconds": { "type": "integer", "minimum": 1 }, "requestBudget": { "type": "integer", "minimum": 1 }, "maxInFlight": { "type": "integer", "minimum": 1 } } }, "BrowserSession": { "type": "object", "required": [ "token", "sessionId", "origin", "scopes", "expiresAt" ], "properties": { "token": { "type": "string", "readOnly": true }, "sessionId": { "type": "string", "format": "uuid" }, "origin": { "type": "string", "format": "uri" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time" } } }, "OperationServiceMode": { "type": "string", "enum": [ "paid", "branding_fallback", "full_fallback" ] }, "TerminalOperation": { "type": "object", "required": [ "operationId", "kind", "status", "serviceMode", "creditsCharged" ], "properties": { "operationId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "generation", "verification", "availability" ] }, "status": { "const": "succeeded" }, "serviceMode": { "$ref": "#/components/schemas/OperationServiceMode" }, "creditsCharged": { "type": "integer", "minimum": 0 } } }, "Dimensions": { "type": "object", "required": [ "width", "height" ], "properties": { "width": { "type": "integer", "minimum": 1 }, "height": { "type": "integer", "minimum": 1 } } }, "CharacterGeometry": { "type": "object", "required": [ "index", "character", "row", "x", "y", "width", "height" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "character": { "type": "string" }, "row": { "type": "integer", "minimum": 0 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 } } }, "RuleCheck": { "type": "object", "required": [ "id", "passed", "message" ], "properties": { "id": { "type": "string" }, "passed": { "type": "boolean" }, "message": { "type": "string" } } }, "Verification": { "type": "object", "required": [ "renderable", "legallyValid", "checks" ], "properties": { "renderable": { "type": "boolean" }, "legallyValid": { "type": "boolean" }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/RuleCheck" } } } }, "AdvisoryContentFlag": { "type": "object", "required": [ "id", "flagged", "message" ], "properties": { "id": { "type": "string" }, "flagged": { "type": "boolean" }, "message": { "type": "string" } } }, "GenerationResult": { "allOf": [ { "$ref": "#/components/schemas/TerminalOperation" }, { "type": "object", "required": [ "shape", "renderedText", "colors", "dimensions", "contentId", "layoutId", "characterGeometry", "effectiveBranding", "artifact" ], "properties": { "kind": { "const": "generation" }, "shape": { "$ref": "#/components/schemas/PlateShape" }, "renderedText": { "type": "string" }, "colors": { "$ref": "#/components/schemas/PlateColors" }, "dimensions": { "$ref": "#/components/schemas/Dimensions" }, "contentId": { "type": "string" }, "layoutId": { "type": "string" }, "characterGeometry": { "type": "array", "items": { "$ref": "#/components/schemas/CharacterGeometry" } }, "effectiveBranding": { "type": "string", "enum": [ "provider", "custom", "none" ] }, "artifact": { "type": "object", "required": [ "id", "url", "expiresAt", "width", "height", "sha256" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "width": { "type": "integer", "minimum": 1 }, "height": { "type": "integer", "minimum": 1 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } } } ] }, "VerificationResult": { "allOf": [ { "$ref": "#/components/schemas/TerminalOperation" }, { "allOf": [ { "$ref": "#/components/schemas/Verification" }, { "type": "object", "required": [ "shape", "text", "advisoryContentFlags" ], "properties": { "kind": { "const": "verification" }, "shape": { "$ref": "#/components/schemas/PlateShape" }, "text": { "type": "string" }, "advisoryContentFlags": { "type": "array", "items": { "$ref": "#/components/schemas/AdvisoryContentFlag" } } } } ] } ] }, "AvailabilityResult": { "allOf": [ { "$ref": "#/components/schemas/TerminalOperation" }, { "type": "object", "required": [ "shape", "text", "verification", "availability", "snapshotId", "retrievedAt", "stale", "disclaimer" ], "properties": { "kind": { "const": "availability" }, "shape": { "$ref": "#/components/schemas/PlateShape" }, "text": { "type": "string" }, "verification": { "$ref": "#/components/schemas/Verification" }, "availability": { "type": "string", "enum": [ "taken", "not_found", "unknown" ] }, "snapshotId": { "type": [ "string", "null" ], "format": "uuid" }, "retrievedAt": { "type": [ "string", "null" ], "format": "date-time" }, "stale": { "type": "boolean" }, "disclaimer": { "type": "string" } } } ] }, "QueuedOperation": { "type": "object", "required": [ "operationId", "operationUrl", "status" ], "properties": { "operationId": { "type": "string", "format": "uuid" }, "operationUrl": { "type": "string" }, "status": { "const": "queued" }, "effectiveBranding": { "type": "string", "enum": [ "provider", "custom", "none" ] }, "serviceMode": { "$ref": "#/components/schemas/OperationServiceMode" }, "creditsReserved": { "type": "integer", "minimum": 0 } } }, "Pricing": { "type": "object", "additionalProperties": false, "required": [ "currency", "vatInclusive", "provisional", "monthlyAllowance", "packs", "costs", "fallback", "artifactRetentionDays" ], "properties": { "currency": { "const": "CZK" }, "vatInclusive": { "type": "boolean" }, "provisional": { "type": "boolean" }, "artifactRetentionDays": { "type": "integer", "minimum": 1 }, "monthlyAllowance": { "type": "object", "additionalProperties": false, "required": [ "credits", "expires" ], "properties": { "credits": { "type": "integer", "minimum": 0 }, "expires": { "const": "calendar_month_utc" } } }, "packs": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CreditPack" } }, "costs": { "type": "object", "additionalProperties": false, "required": [ "brandedGeneration", "customGeneration", "verification", "availability" ], "properties": { "brandedGeneration": { "type": "integer", "minimum": 0 }, "customGeneration": { "type": "integer", "minimum": 0 }, "verification": { "type": "integer", "minimum": 0 }, "availability": { "type": "integer", "minimum": 0 } } }, "fallback": { "type": "object", "additionalProperties": false, "required": [ "brandingDowngrade", "fullFallbackCredits", "separatelyRateLimited" ], "properties": { "brandingDowngrade": { "const": "provider" }, "fullFallbackCredits": { "type": "integer", "minimum": 0 }, "separatelyRateLimited": { "type": "boolean" } } } } }, "CreditPack": { "type": "object", "additionalProperties": false, "required": [ "credits", "amountMinor", "currency" ], "properties": { "credits": { "type": "integer", "minimum": 1 }, "amountMinor": { "type": "integer", "minimum": 0 }, "currency": { "const": "CZK" } } }, "UsageRow": { "type": "object", "additionalProperties": false, "required": [ "day", "kind", "serviceMode", "requestCount", "successCount", "failureCount", "creditsCharged" ], "properties": { "day": { "type": "string", "format": "date" }, "kind": { "type": "string", "enum": [ "generation", "verification", "availability" ] }, "serviceMode": { "$ref": "#/components/schemas/OperationServiceMode" }, "requestCount": { "type": "integer", "minimum": 0 }, "successCount": { "type": "integer", "minimum": 0 }, "failureCount": { "type": "integer", "minimum": 0 }, "creditsCharged": { "type": "integer", "minimum": 0 } } }, "UsagePage": { "type": "object", "additionalProperties": false, "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageRow" } }, "nextCursor": { "type": [ "string", "null" ] } } }, "Operation": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "status", "serviceMode", "creditsReserved", "creditsCharged", "result", "createdAt", "completedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "generation", "verification", "availability" ] }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "serviceMode": { "$ref": "#/components/schemas/OperationServiceMode" }, "creditsReserved": { "type": "integer", "minimum": 0 }, "creditsCharged": { "type": "integer", "minimum": 0 }, "result": { "type": [ "object", "null" ], "additionalProperties": true }, "errorCode": { "type": "string" }, "error": { "$ref": "#/components/schemas/ErrorDetail" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "ErrorDetail": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" }, "details": {} } }, "ErrorEnvelope": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" }, "details": {} } } } } }, "responses": { "BadRequest": { "description": "Malformed request.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Unauthorized": { "description": "A valid credential is required.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Forbidden": { "description": "Credential scope, origin, account, project, or ownership does not permit the request.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "PaymentRequired": { "description": "The requested paid mode cannot be admitted.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "NotFound": { "description": "Resource not found without cross-tenant disclosure.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Conflict": { "description": "Idempotency key reused with different semantics.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Gone": { "description": "The challenge or claim has expired.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "PayloadTooLarge32KiB": { "description": "JSON request body exceeds 32768 bytes.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "PayloadTooLarge4KiB": { "description": "JSON request body exceeds 4096 bytes.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "UnsupportedMediaType": { "description": "Content-Type must be application/json.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ValidationFailed": { "description": "Request validation failed.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimited": { "description": "Capacity exhausted; honor Retry-After.", "headers": { "Retry-After": { "schema": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "format": "http-date" } ] } }, "RateLimit-Policy": { "schema": { "type": "string" } }, "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "TerminalFailure": { "description": "Idempotent replay of a terminal operation failure. The persisted body is a safe error envelope.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Unavailable": { "description": "A trusted caller address or required service dependency is unavailable.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }