{ "openapi": "3.1.0", "info": { "title": "Sorsivo Public Catalog and SEO API", "version": "1.0.0", "description": "Public editorial catalog, free SEO utilities and read-only AI access. No authentication is required for catalog reads. Provider credentials are held by the server; never include them in requests. Private customer records and private SEO audit reports are excluded.", "contact": { "name": "Sorsivo", "url": "https://sorsivo.com/contact" } }, "servers": [ { "url": "https://sorsivo.com" } ], "tags": [ { "name": "Catalog" }, { "name": "Tools" }, { "name": "MCP" } ], "paths": { "/api/public/v1/status": { "get": { "operationId": "getPublicApiStatus", "summary": "Check available features and request limits", "tags": [ "Catalog" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/v1/catalog": { "get": { "operationId": "getPublicCatalog", "summary": "Get the complete reviewed public catalog", "tags": [ "Catalog" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/v1/products": { "get": { "operationId": "searchProducts", "summary": "Search reviewed software products", "tags": [ "Catalog" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Search" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "category", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "tag", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ] } }, "/api/public/v1/products/{slug}": { "get": { "operationId": "getProduct", "summary": "Get a permanent product record", "tags": [ "Catalog" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,118}[a-z0-9])?$" } } ] } }, "/api/public/v1/directories": { "get": { "operationId": "listDirectories", "summary": "List reviewed startup directories", "tags": [ "Catalog" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/v1/taxonomies": { "get": { "operationId": "getTaxonomies", "summary": "List catalog makers, markets, categories, tags, technology and editorial weeks", "tags": [ "Catalog" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Taxonomies" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/v1/leaderboard": { "get": { "operationId": "getDirectoryLeaderboard", "summary": "Get directory Domain Ratings where real provider data is available", "tags": [ "Catalog" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Leaderboard" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/v1/dr": { "post": { "operationId": "checkDomainRatings", "tags": [ "Tools" ], "summary": "Check up to ten domains using Ahrefs", "description": "Real Ahrefs data only. Missing provider configuration returns 503 with null metrics; no estimated ratings.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string" } } }, "required": [ "domains" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainRatings" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Origin rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body or document too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainRatings" } } } }, "502": { "description": "Upstream request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or protection binding unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainRatings" } } } } } } }, "/api/public/v1/seo-check": { "post": { "operationId": "checkSeo", "tags": [ "Tools" ], "summary": "Inspect a public HTTPS page or supplied HTML", "description": "URL mode allows public HTTPS only, checks DNS and each redirect, accepts text/html up to 1 MiB and never forwards credentials. HTML mode does not fetch the optional URL. Checks are heuristics, not a ranking forecast.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ], "additionalProperties": false }, { "type": "object", "properties": { "html": { "type": "string", "minLength": 1, "description": "Maximum 1 MiB UTF-8; parsed without executing scripts." }, "url": { "type": "string", "format": "uri" } }, "required": [ "html" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoCheck" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Origin rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body or document too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or protection binding unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mcp": { "post": { "operationId": "callPublicMcp", "tags": [ "MCP" ], "summary": "Read-only public catalog MCP", "description": "Stateless JSON-RPC over HTTP. Compatibility initialize negotiates 2025-11-25. Current 2026-07-28 requests use matching protocol, method and tool-name headers and protocol metadata. Tools: search_catalog, get_product, list_directories. No enterprise data or write operations.", "parameters": [ { "name": "MCP-Protocol-Version", "in": "header", "schema": { "type": "string" }, "description": "Use 2026-07-28 for current protocol, or the negotiated compatibility version." }, { "name": "MCP-Method", "in": "header", "schema": { "type": "string" }, "description": "Current protocol: must match the JSON-RPC method." }, { "name": "MCP-Name", "in": "header", "schema": { "type": "string" }, "description": "Current tools/call: must match params.name; omit for other methods." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" }, "example": { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": { "name": "example", "version": "1.0" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } }, "202": { "description": "Notification accepted; no response body" }, "400": { "description": "Invalid transport request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Origin rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Only POST is supported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "Source": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "reviewedAt": { "type": "string", "format": "date" } }, "required": [ "label", "url", "reviewedAt" ], "additionalProperties": false }, "Maker": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": [ "slug", "name", "url" ], "additionalProperties": false }, "Product": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "maker": { "$ref": "#/components/schemas/Maker" }, "url": { "type": "string", "format": "uri" }, "tagline": { "type": "string" }, "summary": { "type": "string" }, "editorialDescription": { "type": "string" }, "bestFor": { "type": "array", "items": { "type": "string" } }, "considerBeforeChoosing": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "techStacks": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "items": { "type": "string" } }, "alternativeSlugs": { "type": "array", "items": { "type": "string" } }, "comparisonLinks": { "type": "array", "items": { "type": "object", "properties": { "productSlug": { "type": "string" }, "href": { "type": "string" } }, "required": [ "productSlug", "href" ], "additionalProperties": false } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "firstListedDate": { "type": "string", "format": "date" }, "lastReviewedDate": { "type": "string", "format": "date" }, "week": { "type": "string" } }, "required": [ "slug", "name", "maker", "url", "tagline", "summary", "editorialDescription", "bestFor", "considerBeforeChoosing", "categories", "tags", "techStacks", "countries", "alternativeSlugs", "comparisonLinks", "sources", "firstListedDate", "lastReviewedDate", "week" ], "additionalProperties": false }, "ProductSummary": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "tagline": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "summary": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "firstListedDate": { "type": "string", "format": "date" }, "lastReviewedDate": { "type": "string", "format": "date" }, "alternatives": { "type": "array", "items": { "type": "string" } } }, "required": [ "slug", "name", "tagline", "url", "summary", "categories", "tags", "firstListedDate", "lastReviewedDate", "alternatives" ], "additionalProperties": false }, "Directory": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "submissionUrl": { "type": "string", "format": "uri" }, "sourceUrl": { "type": "string", "format": "uri" }, "audience": { "type": "string" }, "summary": { "type": "string" }, "whenToUse": { "type": "string" }, "submissionGuidance": { "type": "array", "items": { "type": "string" } }, "selectionNotes": { "type": "string" }, "domainRating": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "domainRatingAsOf": { "type": [ "string", "null" ] }, "firstListedDate": { "type": "string", "format": "date" }, "lastReviewedDate": { "type": "string", "format": "date" } }, "required": [ "slug", "name", "url", "submissionUrl", "sourceUrl", "audience", "summary", "whenToUse", "submissionGuidance", "selectionNotes", "domainRating", "domainRatingAsOf", "firstListedDate", "lastReviewedDate" ], "additionalProperties": false }, "Taxonomy": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" }, "productSlugs": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string", "format": "uri" } }, "required": [ "slug", "name", "path", "productSlugs" ], "additionalProperties": false }, "Taxonomies": { "type": "object", "properties": { "makers": { "type": "array", "items": { "$ref": "#/components/schemas/Taxonomy" } }, "countries": { "type": "array", "items": { "$ref": "#/components/schemas/Taxonomy" } }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Taxonomy" } }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/Taxonomy" } }, "techStacks": { "type": "array", "items": { "$ref": "#/components/schemas/Taxonomy" } }, "weeks": { "type": "array", "items": { "$ref": "#/components/schemas/Taxonomy" } } }, "required": [ "makers", "countries", "categories", "tags", "techStacks", "weeks" ], "additionalProperties": false }, "Catalog": { "type": "object", "properties": { "firstListedDate": { "type": "string", "format": "date" }, "reviewedAt": { "type": "string", "format": "date" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "directories": { "type": "array", "items": { "$ref": "#/components/schemas/Directory" } }, "makers": { "type": "array", "items": { "$ref": "#/components/schemas/Taxonomy" } }, "countries": { "type": "array", "items": { "$ref": "#/components/schemas/Taxonomy" } }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Taxonomy" } }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/Taxonomy" } }, "techStacks": { "type": "array", "items": { "$ref": "#/components/schemas/Taxonomy" } }, "weeks": { "type": "array", "items": { "$ref": "#/components/schemas/Taxonomy" } } }, "required": [ "firstListedDate", "reviewedAt", "products", "directories", "makers", "countries", "categories", "tags", "techStacks", "weeks" ], "additionalProperties": false }, "Search": { "type": "object", "properties": { "query": { "type": "string" }, "total": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } } }, "required": [ "query", "total", "items" ], "additionalProperties": false }, "DirectoryList": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Directory" } } }, "required": [ "total", "items" ], "additionalProperties": false }, "Leaderboard": { "type": "object", "properties": { "asOf": { "type": [ "string", "null" ] }, "metric": { "type": "string", "const": "domain-rating" }, "source": { "type": "string" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "domainRating": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "domainRatingAsOf": { "type": [ "string", "null" ] } }, "required": [ "slug", "name", "domainRating", "domainRatingAsOf" ], "additionalProperties": true } } }, "required": [ "asOf", "metric", "source", "entries" ], "additionalProperties": true }, "DomainRatings": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "unavailable" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "domainRating": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "checkedAt": { "type": [ "string", "null" ], "format": "date-time" }, "source": { "type": [ "string", "null" ], "enum": [ "Ahrefs", null ] } }, "required": [ "domain", "domainRating", "checkedAt", "source" ], "additionalProperties": false } }, "reason": { "type": "string" } }, "required": [ "status", "results" ], "additionalProperties": false }, "SeoCheck": { "type": "object", "properties": { "status": { "type": "string", "const": "available" }, "url": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "canonical": { "type": [ "string", "null" ] }, "h1Count": { "type": "integer", "minimum": 0 }, "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "passed": { "type": "boolean" }, "detail": { "type": "string" } }, "required": [ "id", "label", "passed", "detail" ], "additionalProperties": false } }, "summary": { "type": "object", "properties": { "passed": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } }, "required": [ "passed", "total" ], "additionalProperties": false } }, "required": [ "status", "url", "title", "description", "canonical", "h1Count", "checks", "summary" ], "additionalProperties": false }, "JsonRpcRequest": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "number" ] }, "method": { "type": "string" }, "params": { "type": "object", "additionalProperties": true } }, "required": [ "jsonrpc", "method" ], "additionalProperties": false }, "JsonRpcResponse": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "number", "null" ] }, "result": { "type": "object", "additionalProperties": true }, "error": { "type": "object", "additionalProperties": true } }, "required": [ "jsonrpc", "id" ], "additionalProperties": false }, "Status": { "type": "object", "properties": { "status": { "const": "available" }, "service": { "type": "string" }, "version": { "type": "string" }, "features": { "type": "object", "properties": { "catalog": { "type": "boolean" }, "domainRating": { "type": "boolean" }, "seoCheckHtml": { "type": "boolean" }, "seoCheckUrl": { "type": "boolean" }, "mcp": { "type": "boolean" } }, "required": [ "catalog", "domainRating", "seoCheckHtml", "seoCheckUrl", "mcp" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "domainRatingDomainsPerRequest": { "type": "integer" }, "seoCheckHtmlBytes": { "type": "integer" }, "remoteRedirects": { "type": "integer" } }, "required": [ "domainRatingDomainsPerRequest", "seoCheckHtmlBytes", "remoteRedirects" ], "additionalProperties": false } }, "required": [ "status", "service", "version", "features", "limits" ], "additionalProperties": false } } }, "externalDocs": { "description": "Examples and agent setup", "url": "https://sorsivo.com/developers" } }