{ "openapi": "3.1.0", "info": { "title": "SIMOSphere AI Marketing Hub API", "version": "2026-05-18", "summary": "Discovery API for the SIMOSphere AI marketing hub.", "description": "Read-only API exposing the SIMO consulting catalogue, training catalogue, hardware boxes, and discovery call booking. The full platform API (tenants, billing, agents, MCP gateway) is documented separately at https://onboarding.simosphereai.com/openapi.json.\n\n## v2026-05-18 changes\n- Added /api/jobs, /api/tools, /api/capabilities endpoints\n- Added AsyncJob and Error schemas\n- NLWeb /ask now emits token events in SSE stream\n- See https://simosphereai.com/developers/api-versioning for deprecation policy", "contact": { "name": "SIMO GmbH", "email": "info@simo-online.com", "url": "https://simosphereai.com/contact/" }, "license": { "name": "Proprietary", "url": "https://simosphereai.com/impressum/" }, "x-api-version-policy": { "scheme": "date-based (YYYY-MM-DD)", "header": "API-Version", "deprecationHeader": "Deprecation", "sunsetHeader": "Sunset (RFC 8594)", "noticePeriod": "6 months for breaking changes" } }, "servers": [ { "url": "https://simosphereai.com", "description": "Marketing site (public chat, NLWeb, MCP discovery)" }, { "url": "https://api.simosphereai.com", "description": "Platform gateway (workspace + agent API, requires Bearer token)" } ], "tags": [ { "name": "chat", "description": "Public chat + NLWeb endpoints" }, { "name": "mcp", "description": "Model Context Protocol (WebMCP)" }, { "name": "health", "description": "Status + monitoring" }, { "name": "catalogues", "description": "Public read-only catalogues (consulting, hardware, training)" } ], "paths": { "/api/consulting.json": { "get": { "tags": [ "consulting" ], "operationId": "listConsultingPackages", "summary": "List all SIMO consulting packages", "description": "Returns the full SIMO consulting catalogue. Each package has a fixed price, a duration, a margin tier, and a booking URL (Stripe Payment Link for fixed-fee, discovery call URL for custom scopes).", "parameters": [ { "name": "tier", "in": "query", "schema": { "type": "string", "enum": [ "quick-entry", "implementation", "retainer", "all" ] }, "description": "Filter by tier." } ], "responses": { "200": { "description": "Consulting catalogue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsultingCatalogue" } } } } } } }, "/api/training.json": { "get": { "tags": [ "training" ], "operationId": "listTrainings", "summary": "List all SIMO trainings", "responses": { "200": { "description": "Training catalogue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrainingCatalogue" } } } } } } }, "/api/hardware.json": { "get": { "tags": [ "hardware" ], "operationId": "listHardwareBoxes", "summary": "List SIMOSphere AI hardware boxes (Pi / Nuc) and the custom-build path", "responses": { "200": { "description": "Hardware catalogue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HardwareCatalogue" } } } } } } }, "/api/discovery-call.json": { "get": { "tags": [ "discovery" ], "operationId": "getDiscoveryCallUrl", "summary": "Return the discovery call booking URL", "responses": { "200": { "description": "Booking URL", "content": { "application/json": { "schema": { "type": "object", "required": [ "bookingUrl", "duration", "price" ], "properties": { "bookingUrl": { "type": "string", "format": "uri" }, "duration": { "type": "string", "example": "30 minutes" }, "price": { "type": "number", "example": 0 }, "currency": { "type": "string", "example": "EUR" } } } } } } } } }, "/api/site-meta.json": { "get": { "tags": [ "meta" ], "operationId": "getSiteMeta", "summary": "Return site-level metadata for agents", "responses": { "200": { "description": "Site metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteMeta" } } } } } } }, "/api/chat-completion.php": { "post": { "operationId": "chat_completion", "summary": "Send a chat message", "description": "Marketing-side public chat endpoint. Forwards to the SIMO Gateway after HMAC-token validation. Returns markdown answer. Free quota: 20 requests/hour/IP.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } }, "responses": { "200": { "description": "Successful response", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden origin or bot detected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream gateway unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "issue_chat_token", "summary": "Issue HMAC-bound session token", "description": "Returns an ephemeral session token bound to IP + User-Agent. Required header for subsequent POST.", "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "token" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "expires", "min_age" ], "properties": { "token": { "type": "string" }, "expires": { "type": "integer", "format": "int64", "description": "Unix timestamp" }, "min_age": { "type": "integer", "description": "Minimum age in seconds before the token may be used" } } } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ask.php": { "post": { "operationId": "nlweb_ask", "summary": "NLWeb natural-language query", "description": "Microsoft NLWeb-compatible endpoint. Accepts free-text query, returns markdown answer with citations. Supports SSE streaming via Prefer: streaming header.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "streaming" ] }, "description": "Set to \"streaming\" for SSE response (text/event-stream)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskRequest" } } } }, "responses": { "200": { "description": "Successful answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResponse" } }, "text/event-stream": { "schema": { "type": "string", "description": "NLWeb SSE: start → result → complete events" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "nlweb_discovery", "summary": "NLWeb capability discovery", "description": "Returns capabilities, schemas, examples, and streaming support information.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "description": "Capability descriptor" } } } } } } }, "/api/mcp.php": { "get": { "operationId": "mcp_manifest", "summary": "WebMCP server manifest", "description": "Returns Model Context Protocol server manifest with name, version, capabilities, and endpoint URLs.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "operationId": "mcp_rpc", "summary": "WebMCP JSON-RPC 2.0", "description": "JSON-RPC 2.0 endpoint. Supported methods: initialize, tools/list, tools/call, resources/list, resources/read, ping.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "method": { "type": "string" }, "params": { "type": "object" } } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/status.php": { "get": { "operationId": "health_status", "summary": "Health status", "description": "RFC-draft \"API Health Check Format\" compliant health endpoint. Returns runtime, upstream gateway, knowledge-base, cache, and orank-score health checks.", "parameters": [ { "name": "simple", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Return only {\"status\": \"pass|warn|fail\"}" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthStatus" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthStatus" } } } } } } }, "/api/jobs.php": { "post": { "operationId": "submitAsyncJob", "summary": "Submit an async job", "description": "Submit a long-running task. Returns a job_id immediately. Supports Idempotency-Key header for retry-safe submission. Lifecycle: queued → running → succeeded | failed | cancelled.", "tags": [ "jobs" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 64 }, "description": "UUID-style key. Replays within 24h return the original response with Idempotency-Replayed: true header." }, { "name": "API-Version", "in": "header", "schema": { "type": "string", "default": "2026-05-18" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "input" ], "properties": { "type": { "type": "string", "enum": [ "ask", "faq_lookup", "kb_refresh" ] }, "input": { "type": "object", "description": "Type-specific input. For ask: {query, lang?}. For faq_lookup: {question, lang?}. For kb_refresh: {}." } } } } } }, "responses": { "202": { "description": "Job accepted and either queued or completed synchronously.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJob" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large" } } }, "get": { "operationId": "discoverJobs", "summary": "Discover the async-jobs surface", "tags": [ "jobs" ], "responses": { "200": { "description": "Capabilities payload", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/jobs/{id}": { "get": { "operationId": "getJob", "summary": "Get an async job status", "tags": [ "jobs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^job_[a-f0-9]{16}$" } } ], "responses": { "200": { "description": "Job state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJob" } } } }, "404": { "description": "Job not found or expired (30 min TTL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/tools.php": { "get": { "operationId": "listFunctionCallingTools", "summary": "List tools in OpenAI/Anthropic/Mistral/Gemini function-calling format", "tags": [ "tools" ], "parameters": [ { "name": "dialect", "in": "query", "schema": { "type": "string", "enum": [ "openai", "anthropic", "mistral", "gemini" ], "default": "openai" } } ], "responses": { "200": { "description": "Tools array", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/tools/call": { "post": { "operationId": "callTool", "summary": "Execute a tool by name", "tags": [ "tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "enum": [ "ask_simosphere", "list_models", "get_pricing", "faq_lookup", "get_weather", "get_company_info" ] }, "arguments": { "type": "object" } } } } } }, "responses": { "200": { "description": "Tool execution result", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Unknown tool or invalid args", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/capabilities.php": { "get": { "operationId": "getCapabilities", "summary": "Aggregate agent capability index", "tags": [ "discovery" ], "responses": { "200": { "description": "Capability snapshot", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "ConsultingPackage": { "type": "object", "required": [ "id", "name", "tier", "price", "currency", "duration", "bookingType", "bookingUrl" ], "properties": { "id": { "type": "string", "example": "quick-check" }, "name": { "type": "string", "example": "Digitale Souveraenitaet Quick-Check" }, "tier": { "type": "string", "enum": [ "quick-entry", "implementation", "retainer" ] }, "price": { "type": "number", "example": 990 }, "currency": { "type": "string", "example": "EUR" }, "priceMode": { "type": "string", "enum": [ "fixed", "monthly", "per-day" ] }, "duration": { "type": "string", "example": "0.5 days remote" }, "marginPercent": { "type": "integer", "example": 85 }, "summary": { "type": "string" }, "bookingType": { "type": "string", "enum": [ "stripe", "discovery" ] }, "bookingUrl": { "type": "string", "format": "uri" } } }, "ConsultingCatalogue": { "type": "object", "required": [ "packages" ], "properties": { "packages": { "type": "array", "items": { "$ref": "#/components/schemas/ConsultingPackage" } } } }, "Training": { "type": "object", "required": [ "id", "name", "format", "duration", "price", "currency", "bookingUrl" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "audience": { "type": "string", "enum": [ "decision-maker", "compliance", "developer", "power-user" ] }, "format": { "type": "string", "example": "live online" }, "duration": { "type": "string", "example": "2 hours" }, "price": { "type": "number" }, "currency": { "type": "string" }, "perPerson": { "type": "boolean" }, "bookingUrl": { "type": "string", "format": "uri" } } }, "TrainingCatalogue": { "type": "object", "required": [ "trainings" ], "properties": { "trainings": { "type": "array", "items": { "$ref": "#/components/schemas/Training" } } } }, "HardwareBox": { "type": "object", "required": [ "id", "name", "price", "currency", "specs" ], "properties": { "id": { "type": "string", "example": "pi" }, "name": { "type": "string", "example": "SIMOSphere AI Pi" }, "price": { "type": "number", "example": 349 }, "currency": { "type": "string", "example": "EUR" }, "specs": { "type": "object", "properties": { "cpu": { "type": "string" }, "ramGb": { "type": "integer" }, "storageGb": { "type": "integer" }, "defaultLlm": { "type": "string", "example": "Qwen3-8B" } } }, "installPrice": { "type": "number" }, "purchaseUrl": { "type": "string", "format": "uri" } } }, "HardwareCatalogue": { "type": "object", "required": [ "boxes" ], "properties": { "boxes": { "type": "array", "items": { "$ref": "#/components/schemas/HardwareBox" } } } }, "SiteMeta": { "type": "object", "properties": { "name": { "type": "string", "example": "SIMOSphere AI" }, "publisher": { "type": "string", "example": "SIMO GmbH, Aschaffenburg, Germany" }, "tagline": { "type": "string", "example": "Sovereign AI orchestration for European SMEs." }, "languages": { "type": "array", "items": { "type": "string" } }, "subdomains": { "type": "object", "properties": { "marketing": { "type": "string" }, "onboarding": { "type": "string" }, "shop": { "type": "string" } } }, "agentEntrypoints": { "type": "object", "properties": { "llms": { "type": "string" }, "llmsFull": { "type": "string" }, "openapi": { "type": "string" }, "mcp": { "type": "string" }, "agentSkills": { "type": "string" } } } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "type" ], "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "auth_error", "rate_limit", "validation_error", "byok_provider_missing", "server_error", "not_found", "permission_error", "idempotency_conflict" ] }, "code": { "type": "string" }, "param": { "type": "string", "nullable": true }, "retry_after": { "type": "integer", "nullable": true } } } } }, "Pagination": { "type": "object", "properties": { "cursor": { "type": "string", "nullable": true, "description": "Opaque cursor to fetch the next page" }, "has_more": { "type": "boolean" }, "limit": { "type": "integer", "default": 50, "maximum": 200 } } }, "AsyncJob": { "type": "object", "required": [ "job_id", "status" ], "properties": { "job_id": { "type": "string", "pattern": "^job_[a-f0-9]{16}$" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "result_url": { "type": "string", "nullable": true }, "result": { "type": "object", "nullable": true }, "error": { "$ref": "#/components/schemas/Error", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ChatMessage": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant" ] }, "content": { "type": "string", "maxLength": 4000 } } }, "ChatCompletionRequest": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "maxLength": 4000 }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" }, "maxItems": 10 }, "model": { "type": "string", "enum": [ "swiss-ai/apertus-8b-instruct-2509", "mistralai/mistral-large-2" ], "default": "swiss-ai/apertus-8b-instruct-2509" }, "mode": { "type": "string", "enum": [ "online", "demo" ], "default": "online" }, "session_id": { "type": "string", "pattern": "^[a-f0-9]{16,64}$", "nullable": true }, "session_token": { "type": "string", "description": "HMAC-bound token from GET ?action=token" } } }, "ChatCompletionResponse": { "type": "object", "required": [ "success", "content" ], "properties": { "success": { "type": "boolean" }, "content": { "type": "string", "description": "Markdown-formatted answer" }, "model": { "type": "string", "description": "Used model slug or \"faq:*\" or \"tool:*\" or \"demo*\"" }, "mode": { "type": "string" }, "remaining": { "type": "integer", "minimum": 0 }, "session_id": { "type": "string" } } }, "AskRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "maxLength": 4000, "description": "Natural-language question" }, "site": { "type": "string", "format": "uri", "description": "Optional site scope", "default": "https://simosphereai.com" }, "lang": { "type": "string", "enum": [ "de", "en" ], "nullable": true }, "prev": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" }, "maxItems": 8 } } }, "AskResponse": { "type": "object", "required": [ "_meta", "answer" ], "properties": { "_meta": { "type": "object", "required": [ "response_type", "version" ], "properties": { "response_type": { "type": "string", "enum": [ "answer", "error", "capabilities" ] }, "version": { "type": "string" }, "source": { "type": "string", "description": "faq:* | tool:* | llm:* | demo" } } }, "answer": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string", "format": "uri" } }, "follow_up": { "type": "array", "items": { "type": "string" } } } }, "HealthStatus": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pass", "warn", "fail" ] }, "version": { "type": "string" }, "serviceId": { "type": "string" }, "description": { "type": "string" }, "checks": { "type": "object", "additionalProperties": true }, "response_time_ms": { "type": "integer" } } } }, "securitySchemes": { "noAuth": { "type": "apiKey", "in": "header", "name": "X-No-Auth", "description": "Marketing hub endpoints are public, no auth required." }, "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key obtained from https://onboarding.simosphereai.com (format: sk-simo-...). For workspace API on api.simosphereai.com." }, "hmacSessionToken": { "type": "apiKey", "in": "header", "name": "X-Simo-Token", "description": "Ephemeral HMAC token from GET /api/chat-completion.php?action=token. For public marketing chat." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "Client-generated key (8-128 chars, [a-zA-Z0-9_-]) for safe retries of mutation requests. Server caches the first response keyed by this value for 24h.", "required": false, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,128}$" } }, "ApiVersion": { "name": "API-Version", "in": "header", "description": "Optional date-based version pin (YYYY-MM-DD). Defaults to latest.", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "CursorParam": { "name": "after", "in": "query", "description": "Cursor returned by previous page (Pagination.cursor).", "required": false, "schema": { "type": "string" } }, "LimitParam": { "name": "limit", "in": "query", "description": "Page size, max 200.", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200, "minimum": 1 } } }, "headers": { "RateLimit-Limit": { "description": "RFC 9598: request quota and window", "schema": { "type": "string", "example": "20;w=3600" } }, "RateLimit-Remaining": { "description": "RFC 9598: requests left in window", "schema": { "type": "integer", "example": 17 } }, "RateLimit-Reset": { "description": "RFC 9598: seconds until reset", "schema": { "type": "integer", "example": 2340 } }, "Retry-After": { "description": "RFC 7231: seconds before retry", "schema": { "type": "integer" } } } }, "security": [], "webhooks": { "stripeCheckoutCompleted": { "post": { "summary": "Stripe Checkout Session completed", "description": "Outbound webhook from Stripe to /webhook/stripe-log.php. Signed with HMAC-SHA256 via the Stripe-Signature header. Used to log completed Discovery Call, consulting package, and hardware purchases.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Stripe Event payload" } } } }, "responses": { "200": { "description": "Webhook accepted" } } } } }, "externalDocs": { "description": "Full developer documentation", "url": "https://simosphereai.com/developers/llms.txt" } }