{ "openapi": "3.1.0", "info": { "title": "openSERP API", "version": "2.0.0", "description": "Multi-engine search returning all valid unique received results, with inclusive prices, source health, stateless MCP and realtime Markdown retrieval. Paid actions spend prepaid account credits." }, "servers": [ { "url": "https://openserp.io" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Scoped API key from the console. OAuth access tokens are audience-bound to /mcp and cannot call these REST routes." }, "SessionAuth": { "type": "apiKey", "in": "cookie", "name": "__Host-openserp", "description": "Secure console session obtained with Google or GitHub sign-in. Scoped API keys cannot manage account projects or keys." }, "VisitorAuth": { "type": "apiKey", "in": "cookie", "name": "__Host-openserp-visitor", "description": "Anonymous browser linkage issued only when generating a key on the website. Restricted to free search; invalidated when keys attach on login." } }, "schemas": { "SearchRequest": { "type": "object", "required": [ "query" ], "properties": { "endpoint": { "default": "auto.search", "description": "auto.search selects only Google, Bing or Yahoo. Firehose Advanced requires paid access, including cached results. Free accounts may choose engines, including Firehose Lite, using unlimited-age shared cache with automatic routing and provider auto. Free responses exclude full-page content and page Markdown, including cached content. Cache misses run a free live search within the daily allowance. Provider selection and routing preferences require a funded account. Free live searches use the daily allowance.", "type": "string", "maxLength": 80, "enum": [ "auto.search", "firehose.search", "google.search", "bing.search", "yahoo.search", "naver.search", "yandex.search", "baidu.search", "duckduckgo.search", "google.images", "bing.images", "mojeek.search", "deepseek.search", "nimble.search", "exa.search" ] }, "query": { "description": "Search text, at most 2,000 characters after normalization (24,000 encoded input characters). Whitespace, control characters, percent/HTML encoding and typographic quotes are normalized. File-type aliases use each engine’s syntax; quoted operators remain literal. Firehose routes operators only to compatible sources. DeepSeek limits the final query to 128 Unicode characters.", "type": "string", "maxLength": 24000 }, "pageMarkdown": { "description": "Firehose only: false returns search results without fetching page content, reducing cost and response time. true includes page Markdown and requires credits. Omitted paid API requests retain page Markdown; the playground defaults to false.", "type": "boolean" }, "provider": { "default": "auto", "description": "Provider or offering selection requires a funded account. With allowFallback true this is a preference; set false to pin one route. Free searches require auto.", "type": "string", "maxLength": 100 }, "strategy": { "default": "cheap", "description": "Funded accounts may prefer cheap or fast routing. Free searches ignore this preference and always use automatic cache routing.", "type": "string", "enum": [ "cheap", "fast" ] }, "country": { "description": "Country name, native name, ISO alpha-2/alpha-3 or numeric code. USA, U.S. and United States of America normalize to us.", "type": "string", "maxLength": 150 }, "language": { "description": "Language name or code. English/eng normalize to en; regional locale spellings use the base language, with Simplified/Traditional Chinese variants retained.", "type": "string", "maxLength": 150 }, "page": { "default": 1, "type": "integer", "minimum": 1, "maximum": 10 }, "maxPage": { "type": "integer", "minimum": 1, "maximum": 10 }, "maxResults": { "description": "Upstream request target, not a response cap. Defaults to 50 for Firehose (input maximum 100) and 10 otherwise. All valid unique results received are returned, even above the target. Source request limits apply.", "type": "integer", "minimum": 1, "maximum": 1000 }, "timeoutMs": { "type": "integer", "minimum": 5000, "maximum": 30000, "description": "Firehose overall deadline. Default 15000 for fast, 25000 for cheap." }, "maxCostUsd": { "type": [ "string", "number" ] }, "cache": { "default": { "enabled": false, "ttlHours": 24 }, "description": "All cacheable searches reuse results for at least five minutes. enabled false or omitted cache uses a five-minute maximum age; enabled true uses ttlHours, with a five-minute minimum. null means no expiration. Coordinate requests and provider retention restrictions still bypass caching. Cache hits cost zero; free searches reuse shared results of unlimited age. Dedicated page Markdown response caching is private to the account.", "examples": [ { "enabled": true, "ttlHours": 24 } ], "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "ttlHours": { "default": 24, "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 87600 }, { "type": "null" } ] } } }, "firehoseTier": { "description": "Firehose coverage tier. Omitted means lite, the lower search-cost combination. default is a backward-compatible alias for lite. Advanced adds broader coverage at higher search cost. Results use query relevance, weighted source priority and agreement. Lite is available to free and paid users; Advanced requires paid access, including cached results. Free Lite requests reuse shared cache first and search live on a miss, without page Markdown. Applies only to firehose.search.", "type": "string", "enum": [ "lite", "default", "advanced" ] }, "engine": { "type": "string", "maxLength": 40 }, "q": { "type": "string", "maxLength": 24000 }, "allowFallback": { "default": true, "description": "Automatic source selection (provider auto) always retries sources within the selected engine using the cheap or fast strategy, even when this flag is false; it never changes engines after selection. With an explicit provider/offering, false pins one source and one attempt; true allows other sources and compatible engines, preferring viable same-engine sources. Up to three attempts share the deadline and spending cap. Sources with at least ten trailing-hour samples below 90% success remain deprioritized. Compatible web alternatives are Google, Bing and Yahoo; image fallback stays on image engines. Firehose always retries sources within each component engine. Free searches use shared cache first and live search on a miss with managed same-engine source retries.", "type": "boolean" }, "location": { "anyOf": [ { "type": "string", "maxLength": 250 }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } ] }, "domain": { "type": "string", "maxLength": 250 }, "site": { "type": "string", "maxLength": 1000 }, "exactTerms": { "type": "string", "maxLength": 250 }, "excludeTerms": { "type": "string", "maxLength": 250 }, "filetype": { "type": "string", "maxLength": 150 }, "safe": { "description": "off, moderate or strict; on/true normalize to strict. Only compatible sources are eligible.", "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "boolean" } ] }, "device": { "description": "desktop, mobile or tablet; phone/smartphone normalize to mobile.", "type": "string", "maxLength": 40 }, "timePeriod": { "description": "hour, day, week, month or year; aliases such as past week normalize to week.", "type": "string", "maxLength": 80 }, "resultLanguage": { "anyOf": [ { "type": "string", "maxLength": 250 }, { "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 150 } } ] }, "countryRestrict": { "anyOf": [ { "type": "string", "maxLength": 250 }, { "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 150 } } ] }, "noAutocorrect": { "anyOf": [ { "type": "boolean" }, { "type": "string", "maxLength": 20 }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "duplicateFilter": { "anyOf": [ { "type": "boolean" }, { "type": "string", "maxLength": 20 }, { "type": "integer", "minimum": 0, "maximum": 1 } ] } }, "additionalProperties": true }, "MarkdownRequest": { "type": "object", "required": [ "query" ], "properties": { "endpoint": { "default": "auto.search", "description": "auto.search selects only Google, Bing or Yahoo. Firehose Advanced requires paid access, including cached results. Free accounts may choose engines, including Firehose Lite, using unlimited-age shared cache with automatic routing and provider auto. Free responses exclude full-page content and page Markdown, including cached content. Cache misses run a free live search within the daily allowance. Provider selection and routing preferences require a funded account. Free live searches use the daily allowance.", "type": "string", "maxLength": 80, "enum": [ "auto.search", "firehose.search", "google.search", "bing.search", "yahoo.search", "naver.search", "yandex.search", "baidu.search", "duckduckgo.search", "google.images", "bing.images", "mojeek.search", "deepseek.search", "nimble.search", "exa.search" ] }, "query": { "description": "Search text, at most 2,000 characters after normalization (24,000 encoded input characters). Whitespace, control characters, percent/HTML encoding and typographic quotes are normalized. File-type aliases use each engine’s syntax; quoted operators remain literal. Firehose routes operators only to compatible sources. DeepSeek limits the final query to 128 Unicode characters.", "type": "string", "maxLength": 24000 }, "pageMarkdown": { "description": "Firehose only: false returns search results without fetching page content, reducing cost and response time. true includes page Markdown and requires credits. Omitted paid API requests retain page Markdown; the playground defaults to false.", "type": "boolean" }, "provider": { "default": "auto", "description": "Provider or offering selection requires a funded account. With allowFallback true this is a preference; set false to pin one route. Free searches require auto.", "type": "string", "maxLength": 100 }, "strategy": { "default": "cheap", "description": "Funded accounts may prefer cheap or fast routing. Free searches ignore this preference and always use automatic cache routing.", "type": "string", "enum": [ "cheap", "fast" ] }, "country": { "description": "Country name, native name, ISO alpha-2/alpha-3 or numeric code. USA, U.S. and United States of America normalize to us.", "type": "string", "maxLength": 150 }, "language": { "description": "Language name or code. English/eng normalize to en; regional locale spellings use the base language, with Simplified/Traditional Chinese variants retained.", "type": "string", "maxLength": 150 }, "page": { "default": 1, "type": "integer", "minimum": 1, "maximum": 10 }, "maxPage": { "type": "integer", "minimum": 1, "maximum": 10 }, "maxResults": { "description": "Upstream request target, not a response cap. Defaults to 50 for Firehose (input maximum 100) and 10 otherwise. All valid unique results received are returned, even above the target. Source request limits apply.", "type": "integer", "minimum": 1, "maximum": 1000 }, "timeoutMs": { "type": "integer", "minimum": 5000, "maximum": 60000, "default": 45000, "description": "Overall deadline for realtime search and page retrieval. Search gets up to 25000 ms and each page fetch up to 15000 ms within the remaining deadline. Partial results are returned when content is unavailable or the cap is reached." }, "maxCostUsd": { "type": [ "string", "number" ] }, "cache": { "default": { "enabled": false, "ttlHours": 24 }, "description": "All cacheable searches reuse results for at least five minutes. enabled false or omitted cache uses a five-minute maximum age; enabled true uses ttlHours, with a five-minute minimum. null means no expiration. Coordinate requests and provider retention restrictions still bypass caching. Cache hits cost zero; free searches reuse shared results of unlimited age. Dedicated page Markdown response caching is private to the account.", "examples": [ { "enabled": true, "ttlHours": 24 } ], "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "ttlHours": { "default": 24, "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 87600 }, { "type": "null" } ] } } }, "firehoseTier": { "description": "Firehose coverage tier. Omitted means lite, the lower search-cost combination. default is a backward-compatible alias for lite. Advanced adds broader coverage at higher search cost. Results use query relevance, weighted source priority and agreement. Lite is available to free and paid users; Advanced requires paid access, including cached results. Free Lite requests reuse shared cache first and search live on a miss, without page Markdown. Applies only to firehose.search.", "type": "string", "enum": [ "lite", "default", "advanced" ] }, "engine": { "type": "string", "maxLength": 40 }, "q": { "type": "string", "maxLength": 24000 }, "allowFallback": { "default": true, "description": "Automatic source selection (provider auto) always retries sources within the selected engine using the cheap or fast strategy, even when this flag is false; it never changes engines after selection. With an explicit provider/offering, false pins one source and one attempt; true allows other sources and compatible engines, preferring viable same-engine sources. Up to three attempts share the deadline and spending cap. Sources with at least ten trailing-hour samples below 90% success remain deprioritized. Compatible web alternatives are Google, Bing and Yahoo; image fallback stays on image engines. Firehose always retries sources within each component engine. Free searches use shared cache first and live search on a miss with managed same-engine source retries.", "type": "boolean" }, "location": { "anyOf": [ { "type": "string", "maxLength": 250 }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } ] }, "domain": { "type": "string", "maxLength": 250 }, "site": { "type": "string", "maxLength": 1000 }, "exactTerms": { "type": "string", "maxLength": 250 }, "excludeTerms": { "type": "string", "maxLength": 250 }, "filetype": { "type": "string", "maxLength": 150 }, "safe": { "description": "off, moderate or strict; on/true normalize to strict. Only compatible sources are eligible.", "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "boolean" } ] }, "device": { "description": "desktop, mobile or tablet; phone/smartphone normalize to mobile.", "type": "string", "maxLength": 40 }, "timePeriod": { "description": "hour, day, week, month or year; aliases such as past week normalize to week.", "type": "string", "maxLength": 80 }, "resultLanguage": { "anyOf": [ { "type": "string", "maxLength": 250 }, { "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 150 } } ] }, "countryRestrict": { "anyOf": [ { "type": "string", "maxLength": 250 }, { "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 150 } } ] }, "noAutocorrect": { "anyOf": [ { "type": "boolean" }, { "type": "string", "maxLength": 20 }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "duplicateFilter": { "anyOf": [ { "type": "boolean" }, { "type": "string", "maxLength": 20 }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "scraper": { "type": "string", "enum": [ "auto", "scrapingdog", "scrapingbee" ], "default": "auto" } }, "additionalProperties": true } } }, "paths": { "/search": { "post": { "summary": "Firehose: free cached or live Lite results. Advanced and page Markdown require paid access.", "operationId": "firehose", "security": [ { "BearerAuth": [] }, { "SessionAuth": [] }, { "VisitorAuth": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "maxLength": 120 }, "description": "Reusing a completed request key returns its stored result; different inputs return 409." }, { "in": "header", "name": "Accept", "schema": { "type": "string" }, "description": "application/json by default. The website uses application/x-ndjson for realtime progress and a final result in the same request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" }, "example": { "endpoint": "firehose.search", "query": "Cloudflare Workers", "maxCostUsd": "1", "cache": { "enabled": true, "ttlHours": 24 } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "application/x-ndjson": { "schema": { "type": "string" }, "example": "{\"type\":\"progress\",\"phase\":\"searching\"}\n{\"type\":\"result\",\"data\":{}}\n" } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/search": { "post": { "summary": "Search a selected engine; free queries use shared cache with automatic routing and provider auto", "operationId": "search", "security": [ { "BearerAuth": [] }, { "SessionAuth": [] }, { "VisitorAuth": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "maxLength": 120 }, "description": "Reusing a completed request key returns its stored result; different inputs return 409." }, { "in": "header", "name": "Accept", "schema": { "type": "string" }, "description": "application/json by default. The website uses application/x-ndjson for realtime progress and a final result in the same request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" }, "example": { "endpoint": "google.search", "query": "Cloudflare Workers", "maxCostUsd": "1", "cache": { "enabled": true, "ttlHours": 24 } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "application/x-ndjson": { "schema": { "type": "string" }, "example": "{\"type\":\"progress\",\"phase\":\"searching\"}\n{\"type\":\"result\",\"data\":{}}\n" } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/quote": { "post": { "summary": "Compare inclusive prices, median/p90 search latency and source timeouts without paid calls", "operationId": "quote", "security": [ { "BearerAuth": [] }, {} ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "maxLength": 120 }, "description": "Reusing a completed request key returns its stored result; different inputs return 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" }, "example": { "endpoint": "google.search", "query": "Cloudflare Workers", "maxCostUsd": "1", "cache": { "enabled": true, "ttlHours": 24 } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/search/markdown": { "post": { "summary": "Fetch full-page Markdown in realtime. Paid accounts and search permission only", "operationId": "searchMarkdown", "security": [ { "BearerAuth": [] }, { "SessionAuth": [] }, { "VisitorAuth": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "maxLength": 120 }, "description": "Reusing a completed request key returns its stored result; different inputs return 409." }, { "in": "header", "name": "Accept", "schema": { "type": "string" }, "description": "application/json by default. The website uses application/x-ndjson for realtime progress and a final result in the same request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkdownRequest" }, "example": { "endpoint": "google.search", "query": "Cloudflare Workers", "maxCostUsd": "1", "cache": { "enabled": true, "ttlHours": 24 } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "application/x-ndjson": { "schema": { "type": "string" }, "example": "{\"type\":\"progress\",\"phase\":\"searching\"}\n{\"type\":\"result\",\"data\":{}}\n" } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/pricing": { "get": { "summary": "Final starting query prices per 1,000 searches; authenticated requests use account-specific pricing", "operationId": "startingPrices", "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/status": { "get": { "summary": "Seven-day hourly source history, trailing-hour median/p90 search latency and timeout policies", "operationId": "status", "parameters": [ { "in": "query", "name": "engine", "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/account": { "get": { "summary": "Account balance and the authenticated API key’s limits, spend, reservations and remaining allowances", "operationId": "account", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/anonymous/keys": { "post": { "x-browser-only": true, "summary": "Generate or automatically reuse an anonymous key on the website; keys and usage attach on login", "description": "Same-origin browser POST only. The playground calls this on the first Run click. reuseExisting true reconnects a valid existing browser key without issuing or revealing another secret. Generates a secret once, with per-request, daily and total spending limits; sets a Secure HttpOnly visitor cookie. At most three active keys per visitor and network-limited issuance. Search quota is shared by network across keys and login. Sign in in the original browser within 30 days of the first key to keep keys and history. Unclaimed accounts and keys expire after 30 days; responses report expiresAt in milliseconds. Creating more keys does not extend expiry. Use the signed-in console for account keys.", "operationId": "createAnonymousKey", "parameters": [ { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string", "const": "https://openserp.io" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "projectId": { "type": "string", "description": "Project owned by the signed-in account; defaults to the Default project on creation and cannot be changed on an existing key." }, "scopes": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "search", "balance" ] } }, "maxCostUsd": { "oneOf": [ { "type": "string" }, { "type": "number", "exclusiveMinimum": 0, "maximum": 10 } ], "default": "1", "description": "Per-request customer spending cap, at final customer prices. Greater than $0 and at most $10." }, "dailyLimitUsd": { "oneOf": [ { "type": "string" }, { "type": "number", "minimum": 0 }, { "type": "null" } ], "default": null, "description": "Optional daily customer spend limit at final customer prices, reset at 00:00 UTC. Null or blank means unlimited; 0 blocks new paid spend. Active reservations count against the allowance." }, "totalLimitUsd": { "oneOf": [ { "type": "string" }, { "type": "number", "minimum": 0 }, { "type": "null" } ], "default": null, "description": "Optional lifetime customer spend limit at final customer prices. Null or blank means unlimited; 0 blocks new paid spend. Actual charges persist across limit edits and analytics expiry." }, "reuseExisting": { "type": "boolean", "default": false, "description": "Reuse a valid browser-linked key rather than issuing another. Used automatically by the playground." } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/mcp/install-key": { "post": { "x-browser-only": true, "summary": "Generate an account-linked MCP setup key when copying client configuration", "description": "Website Copy setup/Copy agent instructions only. Requires same-origin browser context; Bearer authentication is rejected. A signed-in session creates a key in its Default project; an anonymous visitor gets a browser-linked key and Secure HttpOnly cookie. Anonymous keys and usage attach on login/account creation in the same browser before expiry, 30 days from the first key. New keys have search/balance scopes and $1 per-request, $5 daily and $20 total limits. The page keeps the returned secret only in memory and may supply reuseKey on later copies. Ownership and revocation are rechecked against the current browser; valid reuse preserves project, scopes and limits. No recoverable key is stored server-side. Responses are private/no-store; anonymous issuance limits apply.", "operationId": "mcpInstallKey", "security": [ { "SessionAuth": [] }, { "VisitorAuth": [] }, {} ], "parameters": [ { "in": "header", "name": "Origin", "required": true, "schema": { "type": "string", "const": "https://openserp.io" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "reuseKey": { "type": "string", "writeOnly": true, "pattern": "^osk?_[A-Za-z0-9_-]{20,197}$", "description": "Previously generated secret held in page memory; never place in a URL." } } }, "example": {} } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/projects": { "get": { "summary": "List owned projects and key counts", "operationId": "projects", "security": [ { "SessionAuth": [] } ], "parameters": [], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "summary": "Create a named project", "operationId": "createProject", "security": [ { "SessionAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/projects/{id}": { "patch": { "summary": "Rename a project", "operationId": "renameProject", "security": [ { "SessionAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/keys": { "get": { "summary": "List key limits, actual daily/lifetime spend and reservations without secret values", "operationId": "keys", "security": [ { "SessionAuth": [] } ], "parameters": [ { "in": "query", "name": "projectId", "schema": { "type": "string" } }, { "in": "query", "name": "cursor", "schema": { "type": "string" }, "description": "nextCursor from the previous page; 100 keys per page." } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "summary": "Create a project key with per-request, daily and lifetime spend limits; secret shown once", "operationId": "createKey", "security": [ { "SessionAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "projectId": { "type": "string", "description": "Project owned by the signed-in account; defaults to the Default project on creation and cannot be changed on an existing key." }, "scopes": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "search", "balance" ] } }, "maxCostUsd": { "oneOf": [ { "type": "string" }, { "type": "number", "exclusiveMinimum": 0, "maximum": 10 } ], "default": "1", "description": "Per-request customer spending cap, at final customer prices. Greater than $0 and at most $10." }, "dailyLimitUsd": { "oneOf": [ { "type": "string" }, { "type": "number", "minimum": 0 }, { "type": "null" } ], "default": null, "description": "Optional daily customer spend limit at final customer prices, reset at 00:00 UTC. Null or blank means unlimited; 0 blocks new paid spend. Active reservations count against the allowance." }, "totalLimitUsd": { "oneOf": [ { "type": "string" }, { "type": "number", "minimum": 0 }, { "type": "null" } ], "default": null, "description": "Optional lifetime customer spend limit at final customer prices. Null or blank means unlimited; 0 blocks new paid spend. Actual charges persist across limit edits and analytics expiry." } } } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/keys/{id}": { "patch": { "summary": "Update key name, permissions and per-request, daily or lifetime spend limits", "operationId": "updateKey", "security": [ { "SessionAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "projectId": { "type": "string", "description": "Project owned by the signed-in account; defaults to the Default project on creation and cannot be changed on an existing key." }, "scopes": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "search", "balance" ] } }, "maxCostUsd": { "oneOf": [ { "type": "string" }, { "type": "number", "exclusiveMinimum": 0, "maximum": 10 } ], "default": "1", "description": "Per-request customer spending cap, at final customer prices. Greater than $0 and at most $10." }, "dailyLimitUsd": { "oneOf": [ { "type": "string" }, { "type": "number", "minimum": 0 }, { "type": "null" } ], "default": null, "description": "Optional daily customer spend limit at final customer prices, reset at 00:00 UTC. Null or blank means unlimited; 0 blocks new paid spend. Active reservations count against the allowance." }, "totalLimitUsd": { "oneOf": [ { "type": "string" }, { "type": "number", "minimum": 0 }, { "type": "null" } ], "default": null, "description": "Optional lifetime customer spend limit at final customer prices. Null or blank means unlimited; 0 blocks new paid spend. Actual charges persist across limit edits and analytics expiry." } } } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "delete": { "summary": "Revoke a key while retaining its usage history", "operationId": "revokeKey", "security": [ { "SessionAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/account/usage": { "get": { "summary": "Compare searches and actual charges across keys; includes revoked-key history", "operationId": "keyUsage", "security": [ { "SessionAuth": [] } ], "parameters": [ { "in": "query", "name": "days", "schema": { "type": "integer", "enum": [ 1, 7, 30 ], "default": 7 } }, { "in": "query", "name": "projectId", "schema": { "type": "string" } }, { "in": "query", "name": "keyId", "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/account/exports/payments.csv": { "get": { "summary": "Export complete payment history, status, credit reversals and net credited amounts as CSV", "description": "Exports the authenticated account only. Requires a browser session or API key with balance permission. All history by default; from/to are inclusive UTC calendar dates. Responses stream CSV without queuing a job.", "operationId": "exportPaymentHistory", "security": [ { "SessionAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "from", "schema": { "type": "string", "format": "date" }, "description": "First UTC date, inclusive. Omit for all history." }, { "in": "query", "name": "to", "schema": { "type": "string", "format": "date" }, "description": "Last UTC date, inclusive. Defaults to today; future dates are rejected." } ], "responses": { "200": { "description": "Private CSV download", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "description": "attachment with a generated CSV filename" } }, "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/account/exports/daily-spend.csv": { "get": { "summary": "Export daily UTC wallet spend across all projects and keys, including zero-spend dates, as CSV", "description": "Exports the authenticated account only. Requires a browser session or API key with balance permission. All history by default; from/to are inclusive UTC calendar dates. Responses stream CSV without queuing a job.", "operationId": "exportDailySpendHistory", "security": [ { "SessionAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "from", "schema": { "type": "string", "format": "date" }, "description": "First UTC date, inclusive. Omit for all history." }, { "in": "query", "name": "to", "schema": { "type": "string", "format": "date" }, "description": "Last UTC date, inclusive. Defaults to today; future dates are rejected." } ], "responses": { "200": { "description": "Private CSV download", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "description": "attachment with a generated CSV filename" } }, "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } } } }