{ "openapi": "3.1.0", "info": { "title": "HeyClaude API", "version": "1.0.0", "description": "Read-only registry, distribution feeds, and tightly scoped dynamic endpoints. Public registry publishing is not exposed through the API." }, "servers": [{ "url": "https://heyclau.de" }, { "url": "https://dev.heyclau.de" }], "security": [{ "OriginCheck": [] }], "components": { "schemas": { "ErrorEnvelope": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] }, "RegistryBrandAsset": { "type": "object", "properties": { "brandName": { "type": "string" }, "brandDomain": { "type": "string" }, "brandIconUrl": { "type": "string" }, "brandLogoUrl": { "type": "string" }, "brandAssetSource": { "type": "string" }, "brandVerifiedAt": { "type": "string" }, "brandColors": { "type": "array", "items": { "type": "string" }, "maxItems": 6 } } }, "RegistrySearchResult": { "type": "object", "properties": { "brandName": { "type": "string" }, "brandDomain": { "type": "string" }, "brandIconUrl": { "type": "string" }, "brandLogoUrl": { "type": "string" }, "brandAssetSource": { "type": "string" }, "brandVerifiedAt": { "type": "string" }, "brandColors": { "type": "array", "items": { "type": "string" }, "maxItems": 6 }, "submittedBy": { "type": "string" }, "submittedByUrl": { "type": "string", "format": "uri" }, "submittedAt": { "type": "string" }, "submissionIssueNumber": { "type": "integer", "exclusiveMinimum": 0 }, "submissionIssueUrl": { "type": "string", "format": "uri" }, "importPrNumber": { "type": "integer", "exclusiveMinimum": 0 }, "importPrUrl": { "type": "string", "format": "uri" }, "reviewedBy": { "type": "string" }, "reviewedAt": { "type": "string" }, "claimStatus": { "type": "string", "enum": ["unclaimed", "pending", "verified"] }, "claimedBy": { "type": "string" }, "claimedByUrl": { "type": "string", "format": "uri" }, "claimedAt": { "type": "string" }, "category": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "seoTitle": { "type": "string" }, "description": { "type": "string" }, "seoDescription": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 32 }, "keywords": { "type": "array", "items": { "type": "string" }, "maxItems": 64 }, "author": { "type": "string" }, "safetyNotes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 320 }, "maxItems": 8 }, "privacyNotes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 320 }, "maxItems": 8 }, "dateAdded": { "type": "string" }, "installable": { "type": "boolean" }, "downloadUrl": { "type": "string" }, "downloadTrust": { "type": ["string", "null"] }, "verificationStatus": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" }, "maxItems": 12 }, "supportLevels": { "type": "array", "items": { "type": "string" }, "maxItems": 12 }, "documentationUrl": { "type": "string" }, "repoUrl": { "type": "string" }, "url": { "type": "string" }, "canonicalUrl": { "type": "string", "format": "uri" }, "llmsUrl": { "type": "string", "format": "uri" }, "apiUrl": { "type": "string", "format": "uri" }, "trustSignals": { "type": "object", "properties": { "firstPartyEditorial": { "type": "boolean" }, "packageVerified": { "type": "boolean" }, "packageTrust": { "type": ["string", "null"] }, "packageChecksum": { "type": "string" }, "checksumPresent": { "type": "boolean" }, "sourceUrlCount": { "type": "integer", "minimum": 0 }, "sourceUrls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 8 }, "sourceStatus": { "anyOf": [ { "type": "string", "enum": ["available", "missing"] }, { "type": "string" } ] }, "lastVerifiedAt": { "type": "string" }, "adapterGenerated": { "type": "boolean" }, "platforms": { "type": "array", "items": { "type": "string" }, "maxItems": 12 }, "supportLevels": { "type": "array", "items": { "type": "string" }, "maxItems": 12 } } } }, "required": [ "category", "slug", "title", "description", "tags", "keywords", "author", "dateAdded", "installable", "verificationStatus", "documentationUrl", "repoUrl", "url", "canonicalUrl", "llmsUrl", "apiUrl", "trustSignals" ], "additionalProperties": {} }, "RegistryTrendingResponse": { "type": "object", "properties": { "schemaVersion": { "type": "number" }, "kind": { "type": "string", "enum": ["registry-trending"] }, "category": { "type": "string" }, "platform": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "count": { "type": "integer", "minimum": 0 }, "signalsAvailable": { "type": "object", "properties": { "votes": { "type": "boolean" }, "community": { "type": "boolean" }, "intent": { "type": "boolean" } }, "required": ["votes", "community", "intent"] }, "entries": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "canonicalUrl": { "type": "string", "format": "uri" }, "platforms": { "type": "array", "items": { "type": "string" }, "maxItems": 12 }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 32 }, "dateAdded": { "type": "string" }, "score": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string" }, "maxItems": 6 }, "trustSignals": { "type": "object", "properties": { "sourceStatus": { "type": "string" } }, "required": ["sourceStatus"] } }, "required": [ "category", "slug", "title", "description", "platforms", "tags", "dateAdded", "score", "reasons", "trustSignals" ] }, "maxItems": 50 } }, "required": [ "schemaVersion", "kind", "category", "platform", "limit", "count", "signalsAvailable", "entries" ] }, "RegistryTrustSignals": { "type": "object", "properties": { "firstPartyEditorial": { "type": "boolean" }, "packageVerified": { "type": "boolean" }, "packageTrust": { "type": ["string", "null"] }, "packageChecksum": { "type": "string" }, "checksumPresent": { "type": "boolean" }, "sourceUrlCount": { "type": "integer", "minimum": 0 }, "sourceUrls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 8 }, "sourceStatus": { "anyOf": [{ "type": "string", "enum": ["available", "missing"] }, { "type": "string" }] }, "lastVerifiedAt": { "type": "string" }, "adapterGenerated": { "type": "boolean" }, "platforms": { "type": "array", "items": { "type": "string" }, "maxItems": 12 }, "supportLevels": { "type": "array", "items": { "type": "string" }, "maxItems": 12 } } } }, "parameters": {} }, "paths": { "/api/registry/manifest": { "get": { "tags": ["Registry"], "summary": "Registry artifact manifest", "responses": { "200": { "description": "Cacheable registry response with ETag support where applicable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/registry/categories": { "get": { "tags": ["Registry"], "summary": "Registry category summaries", "responses": { "200": { "description": "Cacheable registry response with ETag support where applicable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/registry/search": { "get": { "tags": ["Registry"], "summary": "Search registry entries", "description": "Search entries by query, category, and platform while preserving bounded result size.", "parameters": [ { "schema": { "type": "string", "maxLength": 120, "default": "" }, "required": false, "name": "q", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9-]+$" }, { "type": "string", "enum": [""] } ], "default": "" }, "required": false, "name": "category", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9][a-z0-9 -]{0,48}$" }, { "type": "string", "enum": [""] } ], "default": "" }, "required": false, "name": "platform", "in": "query" }, { "schema": { "type": "string", "enum": ["all", "true", "false"], "default": "all" }, "required": false, "name": "hasSafetyNotes", "in": "query" }, { "schema": { "type": "string", "enum": ["all", "true", "false"], "default": "all" }, "required": false, "name": "hasPrivacyNotes", "in": "query" }, { "schema": { "type": "string", "enum": ["all", "first-party", "external", "none"], "default": "all" }, "required": false, "name": "downloadTrust", "in": "query" }, { "schema": { "type": "string", "enum": ["all", "unclaimed", "pending", "verified"], "default": "all" }, "required": false, "name": "claimStatus", "in": "query" }, { "schema": { "type": "string", "enum": ["all", "available", "missing"], "default": "all" }, "required": false, "name": "sourceStatus", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": ["integer", "null"], "minimum": 0, "maximum": 10000, "default": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Cacheable registry response with ETag support where applicable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "type": "number" }, "query": { "type": "string" }, "category": { "type": "string" }, "platform": { "type": "string" }, "filters": { "type": "object", "properties": { "hasSafetyNotes": { "type": "string" }, "hasPrivacyNotes": { "type": "string" }, "downloadTrust": { "type": "string" }, "claimStatus": { "type": "string" }, "sourceStatus": { "type": "string" } }, "required": [ "hasSafetyNotes", "hasPrivacyNotes", "downloadTrust", "claimStatus", "sourceStatus" ] }, "count": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "offset": { "type": "integer", "minimum": 0, "maximum": 10000 }, "nextOffset": { "type": ["integer", "null"], "minimum": 0, "maximum": 10000 }, "results": { "type": "array", "items": { "type": "object", "properties": { "brandName": { "type": "string" }, "brandDomain": { "type": "string" }, "brandIconUrl": { "type": "string" }, "brandLogoUrl": { "type": "string" }, "brandAssetSource": { "type": "string" }, "brandVerifiedAt": { "type": "string" }, "brandColors": { "type": "array", "items": { "type": "string" }, "maxItems": 6 }, "submittedBy": { "type": "string" }, "submittedByUrl": { "type": "string", "format": "uri" }, "submittedAt": { "type": "string" }, "submissionIssueNumber": { "type": "integer", "exclusiveMinimum": 0 }, "submissionIssueUrl": { "type": "string", "format": "uri" }, "importPrNumber": { "type": "integer", "exclusiveMinimum": 0 }, "importPrUrl": { "type": "string", "format": "uri" }, "reviewedBy": { "type": "string" }, "reviewedAt": { "type": "string" }, "claimStatus": { "type": "string", "enum": ["unclaimed", "pending", "verified"] }, "claimedBy": { "type": "string" }, "claimedByUrl": { "type": "string", "format": "uri" }, "claimedAt": { "type": "string" }, "category": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "seoTitle": { "type": "string" }, "description": { "type": "string" }, "seoDescription": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 32 }, "keywords": { "type": "array", "items": { "type": "string" }, "maxItems": 64 }, "author": { "type": "string" }, "safetyNotes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 320 }, "maxItems": 8 }, "privacyNotes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 320 }, "maxItems": 8 }, "dateAdded": { "type": "string" }, "installable": { "type": "boolean" }, "downloadUrl": { "type": "string" }, "downloadTrust": { "type": ["string", "null"] }, "verificationStatus": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" }, "maxItems": 12 }, "supportLevels": { "type": "array", "items": { "type": "string" }, "maxItems": 12 }, "documentationUrl": { "type": "string" }, "repoUrl": { "type": "string" }, "url": { "type": "string" }, "canonicalUrl": { "type": "string", "format": "uri" }, "llmsUrl": { "type": "string", "format": "uri" }, "apiUrl": { "type": "string", "format": "uri" }, "trustSignals": { "type": "object", "properties": { "firstPartyEditorial": { "type": "boolean" }, "packageVerified": { "type": "boolean" }, "packageTrust": { "type": ["string", "null"] }, "packageChecksum": { "type": "string" }, "checksumPresent": { "type": "boolean" }, "sourceUrlCount": { "type": "integer", "minimum": 0 }, "sourceUrls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 8 }, "sourceStatus": { "anyOf": [ { "type": "string", "enum": ["available", "missing"] }, { "type": "string" } ] }, "lastVerifiedAt": { "type": "string" }, "adapterGenerated": { "type": "boolean" }, "platforms": { "type": "array", "items": { "type": "string" }, "maxItems": 12 }, "supportLevels": { "type": "array", "items": { "type": "string" }, "maxItems": 12 } } } }, "required": [ "category", "slug", "title", "description", "tags", "keywords", "author", "dateAdded", "installable", "verificationStatus", "documentationUrl", "repoUrl", "url", "canonicalUrl", "llmsUrl", "apiUrl", "trustSignals" ], "additionalProperties": {} }, "maxItems": 50 }, "facets": { "type": "object", "properties": { "categories": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "platforms": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "hasSafetyNotes": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "hasPrivacyNotes": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "downloadTrust": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "claimStatus": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "sourceStatus": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "required": [ "categories", "platforms", "hasSafetyNotes", "hasPrivacyNotes", "downloadTrust", "claimStatus", "sourceStatus" ] } }, "required": [ "schemaVersion", "query", "category", "platform", "count", "total", "limit", "offset", "nextOffset", "results" ] } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/registry/feed": { "get": { "tags": ["Registry"], "summary": "Registry feed discovery", "description": "Discovers API, RSS, changelog, category feeds, platform feeds, category and platform shards, and artifact URLs.", "responses": { "200": { "description": "Cacheable registry response with ETag support where applicable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/registry/trending": { "get": { "tags": ["Registry"], "summary": "Public registry trending entries", "description": "Returns bounded privacy-safe trending registry entries from aggregate votes, community signals, intent events, and static trust metadata.", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9-]+$" }, { "type": "string", "enum": [""] } ], "default": "" }, "required": false, "name": "category", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9][a-z0-9 -]{0,48}$" }, { "type": "string", "enum": [""] } ], "default": "" }, "required": false, "name": "platform", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 12 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Cacheable registry response with ETag support where applicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistryTrendingResponse" } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/registry/diff": { "get": { "tags": ["Registry"], "summary": "Registry changelog diff", "parameters": [ { "schema": { "type": "string", "maxLength": 128, "default": "" }, "required": false, "name": "since", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Cacheable registry response with ETag support where applicable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/registry/integrity": { "get": { "tags": ["Registry"], "summary": "Registry artifact integrity verification", "description": "Lists current registry artifact hashes and verifies submitted artifact/hash pairs against the deployed manifest.", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [""] }, { "type": "string", "maxLength": 160, "pattern": "^\\/?(?:[a-z0-9][a-z0-9._-]*\\/)*(?:[a-z0-9][a-z0-9._-]*)$" } ] }, "required": false, "name": "artifact", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "enum": [""] }, { "type": "string", "pattern": "^[a-f0-9]{64}$" } ] }, "required": false, "name": "hash", "in": "query" } ], "responses": { "200": { "description": "Cacheable registry response with ETag support where applicable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/registry/entries/{category}/{slug}": { "get": { "tags": ["Registry"], "summary": "Registry entry detail", "description": "Returns entry metadata, body content, package facts, platform compatibility, and factual trustSignals when available.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "required": true, "name": "category", "in": "path" }, { "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Cacheable registry response with ETag support where applicable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/registry/entries/{category}/{slug}/llms": { "get": { "tags": ["Registry"], "summary": "Registry entry LLM text export", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "required": true, "name": "category", "in": "path" }, { "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Cacheable registry response with ETag support where applicable.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/mcp": { "post": { "tags": ["MCP"], "summary": "Read-only HeyClaude MCP endpoint", "description": "Exposes no-key read-only HeyClaude MCP tools, resources, and prompts over Streamable HTTP for registry search, discovery, entry detail, copyable assets, comparison, compatibility lookup, install guidance, platform adapters, feed discovery, client setup, and submission draft helpers. This endpoint does not publish registry content, create submissions, open PRs, or host package artifacts.", "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/brand-assets/{kind}/{domain}": { "get": { "tags": ["Distribution"], "summary": "Resolve a cached brand icon or logo", "description": "Returns a cacheable HeyClaude-hosted brand asset backed by Brandfetch when a registry entry has a validated brand domain.", "parameters": [ { "schema": { "type": "string", "enum": ["icon"] }, "required": true, "name": "kind", "in": "path" }, { "schema": { "type": "string", "maxLength": 255 }, "required": true, "name": "domain", "in": "path" } ], "responses": { "200": { "description": "Request accepted.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/votes/query": { "post": { "tags": ["Dynamic"], "summary": "Query vote counts and client state", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9-]+:[a-z0-9-]+$" }, "maxItems": 1000, "default": [] }, "clientId": { "type": "string", "maxLength": 128, "default": "" } } } } } }, "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/votes/toggle": { "post": { "tags": ["Dynamic"], "summary": "Toggle a vote", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z0-9-]+:[a-z0-9-]+$" }, "clientId": { "type": "string", "minLength": 8, "maxLength": 128 }, "vote": { "type": "boolean" } }, "required": ["key", "clientId", "vote"] } } } }, "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/newsletter/subscribe": { "post": { "tags": ["Newsletter"], "summary": "Subscribe an email to the newsletter", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320 }, "segments": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9:_-]+$/i" }, "maxItems": 20, "default": [] }, "source": { "type": "string", "maxLength": 64, "default": "site" } }, "required": ["email"] } } } }, "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/newsletter/webhook": { "post": { "tags": ["Newsletter"], "summary": "Receive Resend webhook events", "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/submissions/preflight": { "post": { "tags": ["Submissions"], "summary": "Preflight a content submission draft", "description": "Runs read-only schema, duplicate, source, package, and safety/privacy checks before a contributor opens a single-entry content PR through the private submission gate. This endpoint never creates issues, labels, branches, pull requests, registry content, or package artifacts.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "object", "additionalProperties": {}, "default": {} }, "honeypot": { "type": "string", "maxLength": 256, "default": "" } } } } } }, "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [true] }, "category": { "type": "string" }, "slug": { "type": "string" }, "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "skipped": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string", "maxLength": 500 }, "maxItems": 32 }, "warnings": { "type": "array", "items": { "type": "string", "maxLength": 500 }, "maxItems": 32 }, "fields": { "type": "object", "additionalProperties": {} } }, "required": ["ok", "skipped", "errors", "warnings", "fields"] }, "risk": { "type": "object", "properties": { "tier": { "type": "string" }, "policyDecision": { "type": "string" }, "policyMatrix": { "type": "object", "additionalProperties": {} }, "reviewFlags": { "type": "array", "items": { "type": "string", "maxLength": 120 }, "maxItems": 32 }, "classificationWarnings": { "type": "array", "items": {}, "maxItems": 32 } }, "required": ["policyMatrix", "reviewFlags", "classificationWarnings"] }, "expectedNotes": { "type": "object", "properties": { "safety": { "type": "boolean" }, "privacy": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string", "maxLength": 500 }, "maxItems": 8 } }, "required": ["safety", "privacy", "reasons"] }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 80 }, "message": { "type": "string", "maxLength": 500 } }, "required": ["code", "message"] }, "maxItems": 24 }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 80 }, "message": { "type": "string", "maxLength": 500 } }, "required": ["code", "message"] }, "maxItems": 24 }, "duplicates": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 160 }, "category": { "type": "string", "maxLength": 80 }, "slug": { "type": "string", "maxLength": 160 }, "title": { "type": "string", "maxLength": 240 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "reasons": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "maxItems": 8 } }, "required": ["key", "category", "slug", "title", "url", "reasons"] }, "maxItems": 5 }, "nextAction": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 160 }, "url": { "type": "string", "maxLength": 4096, "format": "uri" } }, "required": ["label"] }, "valid": { "type": "boolean", "enum": [true] }, "routeSuggestion": { "type": "string", "enum": ["submit_pr"] }, "prPreview": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 300 }, "targetPath": { "type": "string", "maxLength": 240 }, "branchHint": { "type": "string", "maxLength": 200 }, "baseRef": { "type": "string", "maxLength": 120 }, "body": { "type": "string", "maxLength": 32000 } }, "required": ["title", "targetPath", "branchHint", "baseRef", "body"] } }, "required": [ "ok", "category", "slug", "schema", "risk", "expectedNotes", "blockers", "warnings", "duplicates", "nextAction", "valid", "routeSuggestion", "prPreview" ] }, { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [true] }, "category": { "type": "string" }, "slug": { "type": "string" }, "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "skipped": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string", "maxLength": 500 }, "maxItems": 32 }, "warnings": { "type": "array", "items": { "type": "string", "maxLength": 500 }, "maxItems": 32 }, "fields": { "type": "object", "additionalProperties": {} } }, "required": ["ok", "skipped", "errors", "warnings", "fields"] }, "risk": { "type": "object", "properties": { "tier": { "type": "string" }, "policyDecision": { "type": "string" }, "policyMatrix": { "type": "object", "additionalProperties": {} }, "reviewFlags": { "type": "array", "items": { "type": "string", "maxLength": 120 }, "maxItems": 32 }, "classificationWarnings": { "type": "array", "items": {}, "maxItems": 32 } }, "required": ["policyMatrix", "reviewFlags", "classificationWarnings"] }, "expectedNotes": { "type": "object", "properties": { "safety": { "type": "boolean" }, "privacy": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string", "maxLength": 500 }, "maxItems": 8 } }, "required": ["safety", "privacy", "reasons"] }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 80 }, "message": { "type": "string", "maxLength": 500 } }, "required": ["code", "message"] }, "maxItems": 24 }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 80 }, "message": { "type": "string", "maxLength": 500 } }, "required": ["code", "message"] }, "maxItems": 24 }, "duplicates": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 160 }, "category": { "type": "string", "maxLength": 80 }, "slug": { "type": "string", "maxLength": 160 }, "title": { "type": "string", "maxLength": 240 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "reasons": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "maxItems": 8 } }, "required": ["key", "category", "slug", "title", "url", "reasons"] }, "maxItems": 5 }, "nextAction": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 160 }, "url": { "type": "string", "maxLength": 4096, "format": "uri" } }, "required": ["label"] }, "valid": { "type": "boolean", "enum": [false] }, "routeSuggestion": { "type": "string", "enum": ["fix_required", "route_away", "manual_review"] } }, "required": [ "ok", "category", "slug", "schema", "risk", "expectedNotes", "blockers", "warnings", "duplicates", "nextAction", "valid", "routeSuggestion" ], "additionalProperties": false } ] } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/download": { "get": { "tags": ["Distribution"], "summary": "Download generated registry packages", "description": "Serves maintainer-built package artifacts from constrained /downloads paths. Community-submitted archives are not exposed through this endpoint unless maintainers rebuild and verify the artifact.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "required": true, "name": "asset", "in": "query" } ], "responses": { "200": { "description": "Request accepted.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/listing-leads": { "post": { "tags": ["Commercial"], "summary": "Create a commercial listing lead", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["job", "tool", "claim"] }, "tierInterest": { "type": "string", "enum": ["free", "standard", "featured", "sponsored"], "default": "free" }, "contactName": { "type": "string", "minLength": 1, "maxLength": 120 }, "contactEmail": { "type": "string", "maxLength": 320 }, "companyName": { "type": "string", "minLength": 1, "maxLength": 160 }, "listingTitle": { "type": "string", "minLength": 1, "maxLength": 180 }, "websiteUrl": { "type": "string", "maxLength": 2048, "default": "" }, "applyUrl": { "type": "string", "maxLength": 2048, "default": "" }, "message": { "type": "string", "maxLength": 4000, "default": "" } }, "required": ["kind", "contactName", "contactEmail", "companyName", "listingTitle"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/jobs": { "get": { "tags": ["Jobs"], "summary": "List active reviewed jobs", "description": "Returns active D1-backed job listings for public distribution surfaces such as the jobs board and Raycast. Only reviewed active jobs are returned; private lead, review, payment, and contact fields are excluded.", "parameters": [ { "schema": { "type": "string", "maxLength": 120, "default": "" }, "required": false, "name": "q", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "enum": ["free", "standard", "featured", "sponsored"] }, { "type": "string", "enum": ["all"] }, { "type": "string", "enum": [""] } ], "default": "all" }, "required": false, "name": "tier", "in": "query" }, { "schema": { "type": "string", "enum": ["all", "true", "false", ""], "default": "all" }, "required": false, "name": "remote", "in": "query" }, { "schema": { "type": "string", "maxLength": 120, "default": "" }, "required": false, "name": "location", "in": "query" }, { "schema": { "type": "string", "maxLength": 60, "default": "" }, "required": false, "name": "type", "in": "query" }, { "schema": { "type": "string", "enum": ["all", "official_ats", "employer_careers", "employer_submitted", ""], "default": "all" }, "required": false, "name": "sourceKind", "in": "query" }, { "schema": { "type": "string", "enum": ["all", "true", "false", ""], "default": "all" }, "required": false, "name": "compensation", "in": "query" }, { "schema": { "type": "string", "enum": ["all", "true", "false", ""], "default": "all" }, "required": false, "name": "claimedEmployer", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "enum": [""] }, { "type": "string", "format": "date-time" }, { "type": "string", "format": "date" } ], "default": "" }, "required": false, "name": "postedAfter", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "type": "number" }, "kind": { "type": "string", "enum": ["jobs-index"] }, "generatedAt": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "totalAvailable": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0 }, "nextOffset": { "type": ["integer", "null"] }, "entries": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "company": { "type": "string" }, "companyUrl": { "type": "string", "format": "uri" }, "location": { "type": "string" }, "description": { "type": "string" }, "descriptionMd": { "type": "string" }, "type": { "type": "string" }, "postedAt": { "type": "string" }, "compensation": { "type": "string" }, "equity": { "type": "string" }, "bonus": { "type": "string" }, "benefits": { "type": "array", "items": { "type": "string" }, "maxItems": 24 }, "responsibilities": { "type": "array", "items": { "type": "string" }, "maxItems": 24 }, "requirements": { "type": "array", "items": { "type": "string" }, "maxItems": 24 }, "featured": { "type": "boolean" }, "sponsored": { "type": "boolean" }, "applyUrl": { "type": "string" }, "tier": { "type": "string", "enum": ["free", "standard", "featured", "sponsored"] }, "status": { "type": "string", "enum": [ "draft", "pending_review", "active", "stale_pending_review", "closed", "archived" ] }, "source": { "type": "string", "enum": ["manual", "polar", "email", "curated"] }, "sourceKind": { "type": "string", "enum": ["official_ats", "employer_careers", "employer_submitted"] }, "sourceUrl": { "type": "string" }, "firstSeenAt": { "type": "string" }, "lastCheckedAt": { "type": "string" }, "sourceCheckedAt": { "type": "string" }, "curationNote": { "type": "string" }, "claimedEmployer": { "type": "boolean" }, "expiresAt": { "type": "string" }, "isRemote": { "type": "boolean" }, "isWorldwide": { "type": "boolean" }, "webUrl": { "type": "string", "format": "uri" }, "labels": { "type": "array", "items": { "type": "string" }, "maxItems": 24 }, "sourceLabel": { "type": "string" }, "applySourceLabel": { "type": "string" }, "lastVerifiedAt": { "type": "string" } }, "required": [ "slug", "title", "company", "location", "description", "featured", "applyUrl", "webUrl", "labels", "sourceLabel", "applySourceLabel" ], "additionalProperties": {} }, "maxItems": 100 } }, "required": [ "schemaVersion", "kind", "generatedAt", "count", "total", "totalAvailable", "limit", "offset", "nextOffset", "entries" ] } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/jobs/{slug}": { "get": { "tags": ["Jobs"], "summary": "Get one active reviewed job", "description": "Returns one active D1-backed public job listing plus a small related set. Expired, closed, stale, unreviewed, or source-unhealthy jobs return 404.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "type": "number" }, "kind": { "type": "string", "enum": ["jobs-detail"] }, "slug": { "type": "string" }, "generatedAt": { "type": "string" }, "entry": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "company": { "type": "string" }, "companyUrl": { "type": "string", "format": "uri" }, "location": { "type": "string" }, "description": { "type": "string" }, "descriptionMd": { "type": "string" }, "type": { "type": "string" }, "postedAt": { "type": "string" }, "compensation": { "type": "string" }, "equity": { "type": "string" }, "bonus": { "type": "string" }, "benefits": { "type": "array", "items": { "type": "string" }, "maxItems": 24 }, "responsibilities": { "type": "array", "items": { "type": "string" }, "maxItems": 24 }, "requirements": { "type": "array", "items": { "type": "string" }, "maxItems": 24 }, "featured": { "type": "boolean" }, "sponsored": { "type": "boolean" }, "applyUrl": { "type": "string" }, "tier": { "type": "string", "enum": ["free", "standard", "featured", "sponsored"] }, "status": { "type": "string", "enum": [ "draft", "pending_review", "active", "stale_pending_review", "closed", "archived" ] }, "source": { "type": "string", "enum": ["manual", "polar", "email", "curated"] }, "sourceKind": { "type": "string", "enum": ["official_ats", "employer_careers", "employer_submitted"] }, "sourceUrl": { "type": "string" }, "firstSeenAt": { "type": "string" }, "lastCheckedAt": { "type": "string" }, "sourceCheckedAt": { "type": "string" }, "curationNote": { "type": "string" }, "claimedEmployer": { "type": "boolean" }, "expiresAt": { "type": "string" }, "isRemote": { "type": "boolean" }, "isWorldwide": { "type": "boolean" }, "webUrl": { "type": "string", "format": "uri" }, "labels": { "type": "array", "items": { "type": "string" }, "maxItems": 24 }, "sourceLabel": { "type": "string" }, "applySourceLabel": { "type": "string" }, "lastVerifiedAt": { "type": "string" } }, "required": [ "slug", "title", "company", "location", "description", "featured", "applyUrl", "webUrl", "labels", "sourceLabel", "applySourceLabel" ], "additionalProperties": {} }, "related": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "company": { "type": "string" }, "companyUrl": { "type": "string", "format": "uri" }, "location": { "type": "string" }, "description": { "type": "string" }, "descriptionMd": { "type": "string" }, "type": { "type": "string" }, "postedAt": { "type": "string" }, "compensation": { "type": "string" }, "equity": { "type": "string" }, "bonus": { "type": "string" }, "benefits": { "type": "array", "items": { "type": "string" }, "maxItems": 24 }, "responsibilities": { "type": "array", "items": { "type": "string" }, "maxItems": 24 }, "requirements": { "type": "array", "items": { "type": "string" }, "maxItems": 24 }, "featured": { "type": "boolean" }, "sponsored": { "type": "boolean" }, "applyUrl": { "type": "string" }, "tier": { "type": "string", "enum": ["free", "standard", "featured", "sponsored"] }, "status": { "type": "string", "enum": [ "draft", "pending_review", "active", "stale_pending_review", "closed", "archived" ] }, "source": { "type": "string", "enum": ["manual", "polar", "email", "curated"] }, "sourceKind": { "type": "string", "enum": ["official_ats", "employer_careers", "employer_submitted"] }, "sourceUrl": { "type": "string" }, "firstSeenAt": { "type": "string" }, "lastCheckedAt": { "type": "string" }, "sourceCheckedAt": { "type": "string" }, "curationNote": { "type": "string" }, "claimedEmployer": { "type": "boolean" }, "expiresAt": { "type": "string" }, "isRemote": { "type": "boolean" }, "isWorldwide": { "type": "boolean" }, "webUrl": { "type": "string", "format": "uri" }, "labels": { "type": "array", "items": { "type": "string" }, "maxItems": 24 }, "sourceLabel": { "type": "string" }, "applySourceLabel": { "type": "string" }, "lastVerifiedAt": { "type": "string" } }, "required": [ "slug", "title", "company", "location", "description", "featured", "applyUrl", "webUrl", "labels", "sourceLabel", "applySourceLabel" ], "additionalProperties": {} }, "maxItems": 4 } }, "required": ["schemaVersion", "kind", "slug", "generatedAt", "entry", "related"] } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/admin/listing-leads": { "get": { "tags": ["Admin"], "summary": "Token-protected lead review/export endpoint", "parameters": [ { "schema": { "type": "string", "default": "" }, "required": false, "name": "kind", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "new", "pending_review", "approved", "active", "rejected", "expired", "archived" ] }, { "type": "string", "enum": [""] } ], "default": "" }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "default": "" }, "required": false, "name": "format", "in": "query" } ], "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } }, "patch": { "tags": ["Admin"], "summary": "Update listing lead status transition", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0 }, "action": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": ["id", "action"] } } } }, "responses": { "200": { "description": "Status transition accepted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/admin/jobs": { "get": { "tags": ["Admin"], "summary": "Token-protected reviewed jobs list", "description": "Lists D1-backed job records for maintainer review. Public jobs are rendered from active rows only; this admin endpoint can inspect all statuses.", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "draft", "pending_review", "active", "stale_pending_review", "closed", "archived" ] }, { "type": "string", "enum": [""] } ], "default": "" }, "required": false, "name": "status", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "enum": ["free", "standard", "featured", "sponsored"] }, { "type": "string", "enum": [""] } ], "default": "" }, "required": false, "name": "tier", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "enum": ["manual", "polar", "email", "curated"] }, { "type": "string", "enum": [""] } ], "default": "" }, "required": false, "name": "source", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "enum": ["official_ats", "employer_careers", "employer_submitted"] }, { "type": "string", "enum": [""] } ], "default": "" }, "required": false, "name": "sourceKind", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": ["integer", "null"], "minimum": 0, "maximum": 10000, "default": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } }, "post": { "tags": ["Admin"], "summary": "Create or update a reviewed D1 job", "description": "Creates or updates a private D1 job record after maintainer review. This endpoint never writes public repository content.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "title": { "type": "string", "minLength": 4, "maxLength": 180 }, "companyName": { "type": "string", "minLength": 2, "maxLength": 160 }, "companyUrl": { "type": "string", "maxLength": 2048, "default": "" }, "locationText": { "type": "string", "minLength": 2, "maxLength": 160, "default": "Remote" }, "summary": { "type": "string", "minLength": 80, "maxLength": 900 }, "descriptionMd": { "type": "string", "maxLength": 8000, "default": "" }, "employmentType": { "type": "string", "maxLength": 80, "default": "" }, "compensationSummary": { "type": "string", "maxLength": 160, "default": "" }, "equitySummary": { "type": "string", "maxLength": 160, "default": "" }, "bonusSummary": { "type": "string", "maxLength": 160, "default": "" }, "benefits": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 180 }, "maxItems": 16 }, "responsibilities": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 240 }, "maxItems": 12 }, "requirements": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 240 }, "maxItems": 12 }, "applyUrl": { "type": "string", "maxLength": 2048, "default": "" }, "tier": { "type": "string", "enum": ["free", "standard", "featured", "sponsored"], "default": "free" }, "status": { "type": "string", "enum": [ "draft", "pending_review", "active", "stale_pending_review", "closed", "archived" ], "default": "pending_review" }, "source": { "type": "string", "enum": ["manual", "polar", "email", "curated"], "default": "manual" }, "sourceKind": { "type": "string", "enum": ["official_ats", "employer_careers", "employer_submitted"], "default": "employer_submitted" }, "sourceUrl": { "type": "string", "maxLength": 2048, "default": "" }, "firstSeenAt": { "type": "string", "maxLength": 64, "default": "" }, "lastCheckedAt": { "type": "string", "maxLength": 64, "default": "" }, "sourceCheckedAt": { "type": "string", "maxLength": 64, "default": "" }, "staleCheckCount": { "type": ["integer", "null"], "minimum": 0, "maximum": 20, "default": 0 }, "curationNote": { "type": "string", "maxLength": 1200, "default": "" }, "paidPlacementExpiresAt": { "type": "string", "maxLength": 64, "default": "" }, "claimedEmployer": { "type": "boolean", "default": false }, "postedByEmail": { "anyOf": [ { "type": "string", "maxLength": 320, "format": "email" }, { "type": "string", "enum": [""] } ], "default": "" }, "postedAt": { "type": "string", "maxLength": 64, "default": "" }, "expiresAt": { "type": "string", "maxLength": 64, "default": "" }, "isRemote": { "type": "boolean", "default": true }, "isWorldwide": { "type": "boolean", "default": false } }, "required": ["slug", "title", "companyName", "summary", "applyUrl"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } }, "patch": { "tags": ["Admin"], "summary": "Transition reviewed D1 job state", "description": "Transitions reviewed job rows through active, stale, closed, archived, and revalidated states without publishing repo content.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "action": { "type": "string", "enum": [ "review", "activate", "stale", "close", "archive", "reactivate", "expire", "revalidate" ] }, "checkedAt": { "type": "string", "maxLength": 64, "default": "" }, "expiresAt": { "anyOf": [{ "type": "string", "maxLength": 64 }, { "type": "null" }] } }, "required": ["slug", "action"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/admin/jobs/health": { "get": { "tags": ["Admin"], "summary": "Token-protected D1 jobs health check", "description": "Checks the jobs D1 schema, required columns, and status counts before release or operational review.", "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/intent-events": { "post": { "tags": ["Dynamic"], "summary": "Store a low-risk intent event", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": ["copy", "open", "install", "download", "vote"] }, "entryKey": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9-]+:[a-z0-9-]+$" }, { "type": "string", "enum": [""] } ], "default": "" }, "sessionId": { "type": "string", "maxLength": 128, "default": "" } }, "required": ["type"] } } } }, "responses": { "200": { "description": "Request accepted. D1 insert failed or unavailable states return a documented fail-open response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/community-signals": { "get": { "tags": ["Dynamic"], "summary": "Read community signal counts", "parameters": [ { "schema": { "type": "string", "enum": ["entry", "tool"] }, "required": true, "name": "targetKind", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160 }, "required": true, "name": "targetKey", "in": "query" } ], "responses": { "200": { "description": "Request accepted. Dynamic state may fail open when D1 is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } }, "post": { "tags": ["Dynamic"], "summary": "Store community signal state", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "targetKind": { "type": "string", "enum": ["entry", "tool"] }, "targetKey": { "type": "string", "minLength": 1, "maxLength": 160 }, "signalType": { "type": "string", "enum": ["used", "works", "broken"] }, "clientId": { "type": "string", "minLength": 8, "maxLength": 128 }, "active": { "type": "boolean", "default": true } }, "required": ["targetKind", "targetKey", "signalType", "clientId"] } } } }, "responses": { "200": { "description": "Request accepted. Dynamic state may fail open when D1 is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/community-signals/query": { "post": { "tags": ["Dynamic"], "summary": "Read community signal counts for multiple targets", "description": "Returns aggregate used/works/broken counts for up to 100 entry or tool targets without exposing client identifiers.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": { "type": "array", "items": { "type": "object", "properties": { "targetKind": { "type": "string", "enum": ["entry", "tool"] }, "targetKey": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": ["targetKind", "targetKey"] }, "maxItems": 100, "default": [] } } } } } }, "responses": { "200": { "description": "Request accepted. Dynamic state may fail open when D1 is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/github-stats": { "get": { "tags": ["Dynamic"], "summary": "Read cached GitHub repository stats", "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "repo": { "type": "string" }, "stars": { "type": ["number", "null"] }, "forks": { "type": ["number", "null"] }, "updatedAt": { "type": ["string", "null"] } }, "required": ["repo", "stars", "forks", "updatedAt"] } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/public/alerts": { "get": { "tags": ["Dynamic"], "summary": "Read public registry alert events", "description": "Returns the current in-edge-cache registry event list used by browser-local watch alerts. Cold cache or missing webhook configuration returns an empty events array rather than simulated activity.", "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "category": { "type": "string" }, "slug": { "type": "string" }, "action": { "type": "string" }, "date": { "type": "string" }, "title": { "type": "string" }, "commit": { "type": "string" } }, "additionalProperties": {} }, "maxItems": 500 } }, "required": ["events"] } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/public/feeds/health": { "get": { "tags": ["Distribution"], "summary": "Read public feed health metadata", "description": "Returns deterministic feed item counts, freshness, and ETag metadata for every public distribution feed.", "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "generatedAt": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "feeds": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "itemCount": { "type": "integer", "minimum": 0 }, "latestItemAt": { "type": ["string", "null"] }, "lastBuilt": { "type": "string" }, "etag": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "required": [ "id", "title", "url", "itemCount", "latestItemAt", "lastBuilt", "etag", "isCurrent" ] }, "maxItems": 100 } }, "required": ["generatedAt", "count", "feeds"] } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/api/og": { "get": { "tags": ["Distribution"], "summary": "Generate social preview image", "parameters": [ { "schema": { "type": "string", "maxLength": 120, "default": "HeyClaude" }, "required": false, "name": "title", "in": "query" }, { "schema": { "type": "string", "maxLength": 220, "default": "A Claude-native registry for agents, MCP servers, skills, commands, hooks, rules, guides, and tools." }, "required": false, "name": "description", "in": "query" }, { "schema": { "type": "string", "maxLength": 64, "default": "Registry" }, "required": false, "name": "label", "in": "query" }, { "schema": { "type": "string", "enum": ["registry", "category", "entry", "job", "tool", "platform"], "default": "registry" }, "required": false, "name": "kind", "in": "query" }, { "schema": { "type": "string", "maxLength": 64, "default": "heyclau.de" }, "required": false, "name": "badge", "in": "query" } ], "responses": { "200": { "description": "Request accepted.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid JSON, invalid query, invalid payload, or invalid status transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "401": { "description": "Unauthorized admin token or invalid webhook signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "403": { "description": "Forbidden origin.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "415": { "description": "Invalid content type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "429": { "description": "Route-level or Cloudflare-native rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "502": { "description": "Upstream provider error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } }, "503": { "description": "Site DB not configured, provider not configured, or endpoint unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "details": {} }, "required": ["code"] }, "requestId": { "type": "string" } }, "required": ["ok", "error"] } } } } } } }, "/feed.xml": { "get": { "tags": ["Distribution"], "summary": "RSS feed", "responses": { "200": { "description": "RSS feed", "content": { "application/rss+xml": { "schema": { "type": "string" } } } } } } }, "/atom.xml": { "get": { "tags": ["Distribution"], "summary": "Atom feed", "responses": { "200": { "description": "Atom feed", "content": { "application/atom+xml": { "schema": { "type": "string" } } } } } } }, "/data/feeds/index.json": { "get": { "tags": ["Distribution"], "summary": "Static feed index", "responses": { "200": { "description": "Static feed index", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } } } } }, "/data/feeds/categories/{category}.json": { "get": { "tags": ["Distribution"], "summary": "Static category feed", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "required": true, "name": "category", "in": "path" } ], "responses": { "200": { "description": "Static category feed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } } } } }, "/data/feeds/platforms/{platform}.json": { "get": { "tags": ["Distribution"], "summary": "Static platform feed", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "required": true, "name": "platform", "in": "path" } ], "responses": { "200": { "description": "Static platform feed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } } } } } }, "webhooks": {} }