{"openapi":"3.1.0","info":{"title":"Opstt Public Catalog API","version":"1.8.0","description":"Read-only public API and machine-readable discovery endpoints for published tool listings, taxonomies, updates, and AI agent integration."},"servers":[{"url":"https://opstt.com"}],"tags":[{"name":"Public API","description":"Machine-readable directory access"},{"name":"Discovery","description":"Agent discovery and update monitoring endpoints"}],"components":{"parameters":{"LocaleParam":{"name":"locale","in":"query","schema":{"type":"string","enum":["en","zh","es","pt","de","fr","it","ja","id","ms","th","vi","tl"],"default":"en"},"description":"Requested locale. Unsupported values fall back to the default locale."},"PageParam":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"1-based page number. Invalid values fall back to 1."},"LimitParam":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Requested page size. Invalid values fall back to 20 and values above the max are clamped."},"ItemTypeParam":{"name":"type","in":"query","schema":{"type":"string"},"description":"Optional item type filter."},"FeaturedParam":{"name":"featured","in":"query","schema":{"type":"boolean"},"description":"Optional featured flag filter."},"CategoryParam":{"name":"category","in":"query","schema":{"type":"string"},"description":"Optional comma-separated category slugs."},"TagParam":{"name":"tag","in":"query","schema":{"type":"string"},"description":"Optional comma-separated tag slugs."},"UpdatedAfterParam":{"name":"updated_after","in":"query","schema":{"type":"string","format":"date-time"},"description":"Optional ISO-8601 timestamp for freshness filtering."},"ItemSlugParam":{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},"TaxonomyTypeParam":{"name":"type","in":"query","schema":{"type":"string","enum":["category","tag"],"default":"category"}},"StatusParam":{"name":"status","in":"query","schema":{"type":"string","default":"published"}}},"schemas":{"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","limit","total","totalPages"]},"PublicItemFilters":{"type":"object","properties":{"type":{"type":["string","null"]},"featured":{"type":["boolean","null"]},"categories":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"updatedAfter":{"type":["string","null"],"format":"date-time"}},"required":["type","featured","categories","tags","updatedAfter"]},"TaxonomySummary":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"type":{"type":"string"}},"required":["id","slug","title","type"]},"ItemFreshness":{"type":"object","description":"Machine-readable freshness layer for ranking, recrawl scheduling, and review cadence decisions.","properties":{"lastChangedAt":{"type":"string","format":"date-time"},"publishedAt":{"type":"string","format":"date-time"},"contentUpdatedAt":{"type":["string","null"],"format":"date-time"},"recordUpdatedAt":{"type":"string","format":"date-time"},"enrichedAt":{"type":["string","null"],"format":"date-time"},"reviewedAt":{"type":["string","null"],"format":"date-time"},"recommendedReviewWindowDays":{"type":"integer"},"reviewDueAt":{"type":["string","null"],"format":"date-time"},"recrawlHints":{"type":"array","items":{"type":"string"}}},"required":["lastChangedAt","publishedAt","contentUpdatedAt","recordUpdatedAt","enrichedAt","reviewedAt","recommendedReviewWindowDays","reviewDueAt","recrawlHints"]},"ItemEvidence":{"type":"object","description":"Machine-readable evidence basis for judging whether a listing is officially sourced, reviewed, or directory-only.","properties":{"basisLevel":{"type":"string","enum":["verified","mixed","basic"]},"officialSourceUrl":{"type":["string","null"],"format":"uri"},"sourceHost":{"type":["string","null"]},"officialSourceAvailable":{"type":"boolean"},"manualReviewAvailable":{"type":"boolean"},"structuredAttributesAvailable":{"type":"boolean"},"writtenContentAvailable":{"type":"boolean"},"evidenceSummary":{"type":"string"},"evidenceSources":{"type":"array","items":{"type":"string"}}},"required":["basisLevel","officialSourceUrl","sourceHost","officialSourceAvailable","manualReviewAvailable","structuredAttributesAvailable","writtenContentAvailable","evidenceSummary","evidenceSources"]},"ItemTrustSignalsSummary":{"type":"object","properties":{"reviewedAt":{"type":["string","null"],"format":"date-time"},"reviewedBy":{"type":["string","null"]},"sourceHost":{"type":["string","null"]},"pricing":{"type":"array","items":{"type":"string"}},"platforms":{"type":"array","items":{"type":"string"}},"integrations":{"type":"array","items":{"type":"string"}},"regions":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"}},"verificationNote":{"type":["string","null"]}},"required":["reviewedAt","reviewedBy","sourceHost","pricing","platforms","integrations","regions","languages","verificationNote"]},"PublicItemSummary":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"locale":{"type":"string"},"type":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"publicUrl":{"type":"string","format":"uri"},"officialUrl":{"type":["string","null"],"format":"uri"},"faviconUrl":{"type":["string","null"],"format":"uri"},"coverUrl":{"type":["string","null"],"format":"uri"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"publishedAt":{"type":["string","null"],"format":"date-time"},"enrichedAt":{"type":["string","null"],"format":"date-time"},"isFeatured":{"type":"boolean"},"taxonomies":{"type":"array","items":{"$ref":"#/components/schemas/TaxonomySummary"}},"freshness":{"$ref":"#/components/schemas/ItemFreshness"},"evidence":{"$ref":"#/components/schemas/ItemEvidence"},"trustSignals":{"$ref":"#/components/schemas/ItemTrustSignalsSummary"}},"required":["id","slug","locale","type","title","description","publicUrl","officialUrl","faviconUrl","coverUrl","createdAt","updatedAt","publishedAt","enrichedAt","isFeatured","taxonomies","freshness","evidence","trustSignals"]},"LocalizedAlternates":{"type":"object","properties":{"languages":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"slugs":{"type":"object","additionalProperties":{"type":"string"}}},"required":["languages","slugs"]},"FAQItem":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"]},"ItemAttributeValue":{"type":"object","properties":{"locale":{"type":["string","null"]},"valueString":{"type":["string","null"]},"valueNumber":{"type":["number","null"]},"valueBool":{"type":["boolean","null"]},"valueDate":{"type":["string","null"],"format":"date-time"},"valueJson":{},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["locale","valueString","valueNumber","valueBool","valueDate","valueJson","updatedAt"]},"ItemAttribute":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"},"uiHint":{"type":["string","null"]},"values":{"type":"array","items":{"$ref":"#/components/schemas/ItemAttributeValue"}}},"required":["key","title","uiHint","values"]},"AuthorSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"image":{"type":["string","null"],"format":"uri"},"jobTitle":{"type":["string","null"]}},"required":["id","name","image","jobTitle"]},"ReviewerSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"image":{"type":["string","null"],"format":"uri"}},"required":["id","name","image"]},"AuditInfo":{"type":"object","properties":{"lastReviewedAt":{"type":["string","null"],"format":"date-time"},"reviewer":{"oneOf":[{"$ref":"#/components/schemas/ReviewerSummary"},{"type":"null"}]}},"required":["lastReviewedAt","reviewer"]},"ItemTrustSignalsDetail":{"type":"object","properties":{"officialUrl":{"type":["string","null"],"format":"uri"},"sourceHost":{"type":["string","null"]},"reviewedAt":{"type":["string","null"],"format":"date-time"},"reviewedBy":{"type":["string","null"]},"contentUpdatedAt":{"type":"string","format":"date-time"},"recordUpdatedAt":{"type":"string","format":"date-time"},"publishedAt":{"type":"string","format":"date-time"},"enrichedAt":{"type":["string","null"],"format":"date-time"},"pricing":{"type":"object","properties":{"values":{"type":"array","items":{"type":"string"}},"updatedAt":{"type":["string","null"]}},"required":["values","updatedAt"]},"platforms":{"type":"array","items":{"type":"string"}},"integrations":{"type":"array","items":{"type":"string"}},"regions":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"}},"evidenceSources":{"type":"array","items":{"type":"string"}},"verificationNote":{"type":["string","null"]}},"required":["officialUrl","sourceHost","reviewedAt","reviewedBy","contentUpdatedAt","recordUpdatedAt","publishedAt","enrichedAt","pricing","platforms","integrations","regions","languages","evidenceSources","verificationNote"]},"PublicItemDetail":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"locale":{"type":"string"},"type":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"publicUrl":{"type":"string","format":"uri"},"officialUrl":{"type":["string","null"],"format":"uri"},"faviconUrl":{"type":["string","null"],"format":"uri"},"coverUrl":{"type":["string","null"],"format":"uri"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"publishedAt":{"type":["string","null"],"format":"date-time"},"enrichedAt":{"type":["string","null"],"format":"date-time"},"isFeatured":{"type":"boolean"},"taxonomies":{"type":"array","items":{"$ref":"#/components/schemas/TaxonomySummary"}},"freshness":{"$ref":"#/components/schemas/ItemFreshness"},"evidence":{"$ref":"#/components/schemas/ItemEvidence"},"canonicalUrl":{"type":"string","format":"uri"},"alternates":{"$ref":"#/components/schemas/LocalizedAlternates"},"contentMarkdown":{"type":"string"},"faq":{"type":"array","items":{"$ref":"#/components/schemas/FAQItem"}},"attributes":{"type":"array","items":{"$ref":"#/components/schemas/ItemAttribute"}},"author":{"oneOf":[{"$ref":"#/components/schemas/AuthorSummary"},{"type":"null"}]},"audit":{"$ref":"#/components/schemas/AuditInfo"},"trustSignals":{"$ref":"#/components/schemas/ItemTrustSignalsDetail"}},"required":["id","slug","locale","type","title","description","publicUrl","officialUrl","faviconUrl","coverUrl","createdAt","updatedAt","publishedAt","enrichedAt","isFeatured","taxonomies","freshness","evidence","canonicalUrl","alternates","contentMarkdown","faq","attributes","author","audit","trustSignals"]},"PublicItemListResponse":{"type":"object","properties":{"apiVersion":{"type":"string"},"locale":{"type":"string"},"filters":{"$ref":"#/components/schemas/PublicItemFilters"},"pagination":{"$ref":"#/components/schemas/Pagination"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PublicItemSummary"}}},"required":["apiVersion","locale","filters","pagination","items"]},"PublicTaxonomy":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"}},"required":["id","slug","title","type","status"]},"PublicTaxonomyListResponse":{"type":"object","properties":{"apiVersion":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PublicTaxonomy"}}},"required":["apiVersion","type","status","items"]},"PublicUpdate":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"content":{"type":"string"},"publicUrl":{"type":"string","format":"uri"},"date":{"type":["string","null"]},"version":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"updatedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"}},"required":["id","slug","title","description","content","publicUrl","date","version","tags","updatedAt","createdAt"]},"PublicUpdatesResponse":{"type":"object","properties":{"apiVersion":{"type":"string"},"locale":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PublicUpdate"}}},"required":["apiVersion","locale","items"]},"PublicApiPolicies":{"type":"object","properties":{"cache":{"type":"object","properties":{"cacheControl":{"type":"string"},"browserMaxAgeSeconds":{"type":"integer"},"sharedMaxAgeSeconds":{"type":"integer"},"staleWhileRevalidateSeconds":{"type":"integer"},"xRobotsTag":{"type":"string"},"guidance":{"type":"string"}},"required":["cacheControl","browserMaxAgeSeconds","sharedMaxAgeSeconds","staleWhileRevalidateSeconds","xRobotsTag","guidance"]},"crawl":{"type":"object","properties":{"bootstrapOrder":{"type":"array","items":{"type":"string"}},"recrawlTriggers":{"type":"array","items":{"type":"string"}},"citationRules":{"type":"array","items":{"type":"string"}}},"required":["bootstrapOrder","recrawlTriggers","citationRules"]},"versioning":{"type":"object","properties":{"currentVersion":{"type":"string"},"strategy":{"type":"string"},"breakingChangePolicy":{"type":"string"},"stabilityNotes":{"type":"array","items":{"type":"string"}}},"required":["currentVersion","strategy","breakingChangePolicy","stabilityNotes"]},"freshness":{"type":"object","additionalProperties":{"type":"string"}},"evidence":{"type":"object","additionalProperties":{"type":"string"}},"sourceHealth":{"type":"object","additionalProperties":{"type":"string"}},"errors":{"type":"object","properties":{"parameterNormalization":{"type":"array","items":{"type":"string"}},"itemDetailNotFound":{"type":"object","properties":{"status":{"type":"integer"},"error":{"type":"string"},"message":{"type":"string"}},"required":["status","error","message"]}},"required":["parameterNormalization","itemDetailNotFound"]}},"required":["cache","crawl","versioning","freshness","evidence","sourceHealth","errors"]},"PublicApiIndex":{"type":"object","properties":{"apiVersion":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"baseUrl":{"type":"string","format":"uri"},"defaultLocale":{"type":"string"},"locales":{"type":"array","items":{"type":"string"}},"docs":{"type":"object","properties":{"openapi":{"type":"string","format":"uri"},"llms":{"type":"string","format":"uri"},"developers":{"type":"string","format":"uri"},"agentManifest":{"type":"string","format":"uri"},"wellKnownAgentManifest":{"type":"string","format":"uri"},"updatesFeed":{"type":"string","format":"uri"}},"required":["openapi","llms","developers","agentManifest","wellKnownAgentManifest","updatesFeed"]},"endpoints":{"type":"object","properties":{"self":{"type":"string","format":"uri"},"items":{"type":"string","format":"uri"},"itemsFiltered":{"type":"string","format":"uri"},"item":{"type":"string","format":"uri"},"taxonomies":{"type":"string","format":"uri"},"updates":{"type":"string","format":"uri"},"feed":{"type":"string","format":"uri"},"manifest":{"type":"string","format":"uri"}},"required":["self","items","itemsFiltered","item","taxonomies","updates","feed","manifest"]},"policies":{"$ref":"#/components/schemas/PublicApiPolicies"}},"required":["apiVersion","name","description","baseUrl","defaultLocale","locales","docs","endpoints","policies"]},"AgentManifest":{"type":"object","properties":{"manifestVersion":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"homepage":{"type":"string","format":"uri"},"manifestUrl":{"type":"string","format":"uri"},"wellKnownManifestUrl":{"type":"string","format":"uri"},"documentationUrl":{"type":"string","format":"uri"},"defaultLocale":{"type":"string"},"locales":{"type":"array","items":{"type":"string"}},"authentication":{"type":"object","properties":{"type":{"type":"string"},"required":{"type":"boolean"}},"required":["type","required"]},"discovery":{"type":"object","properties":{"llms":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"publicApi":{"type":"string","format":"uri"},"developerDocs":{"type":"string","format":"uri"},"wellKnownAgentManifest":{"type":"string","format":"uri"},"updatesFeed":{"type":"string","format":"uri"}},"required":["llms","openapi","publicApi","developerDocs","wellKnownAgentManifest","updatesFeed"]},"capabilities":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"contentType":{"type":"string"},"description":{"type":"string"}},"required":["name","url","contentType","description"]}},"queryParameters":{"type":"object","additionalProperties":{"type":"string"}},"citationPolicy":{"type":"object","properties":{"preferCanonicalLocalizedUrls":{"type":"boolean"},"avoidPrivateChatUrls":{"type":"boolean"},"preferItemDetailPagesForClaims":{"type":"boolean"},"preferPublicApiForAutomation":{"type":"boolean"}},"required":["preferCanonicalLocalizedUrls","avoidPrivateChatUrls","preferItemDetailPagesForClaims","preferPublicApiForAutomation"]}},"required":["manifestVersion","name","description","homepage","manifestUrl","wellKnownManifestUrl","documentationUrl","defaultLocale","locales","authentication","discovery","capabilities","resources","queryParameters","citationPolicy"]},"JsonFeedItem":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"summary":{"type":["string","null"]},"content_text":{"type":"string"},"date_published":{"type":["string","null"],"format":"date-time"},"date_modified":{"type":["string","null"],"format":"date-time"},"tags":{"type":"array","items":{"type":"string"}}},"required":["id","url","title","summary","content_text","date_published","date_modified","tags"]},"JsonFeed":{"type":"object","properties":{"version":{"type":"string","format":"uri"},"title":{"type":"string"},"home_page_url":{"type":"string","format":"uri"},"feed_url":{"type":"string","format":"uri"},"description":{"type":"string"},"language":{"type":"string"},"icon":{"type":"string","format":"uri"},"favicon":{"type":"string","format":"uri"},"authors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["name","url"]}},"items":{"type":"array","items":{"$ref":"#/components/schemas/JsonFeedItem"}}},"required":["version","title","home_page_url","feed_url","description","language","icon","favicon","authors","items"]},"NotFoundError":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}},"paths":{"/api/public":{"get":{"tags":["Public API"],"summary":"Public API index","description":"Returns discovery metadata, supported locales, documentation links, and stable endpoint links.","responses":{"200":{"description":"Public API index","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiIndex"}}}}}}},"/api/public/items":{"get":{"tags":["Public API"],"summary":"List published items","parameters":[{"$ref":"#/components/parameters/LocaleParam"},{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/ItemTypeParam"},{"$ref":"#/components/parameters/FeaturedParam"},{"$ref":"#/components/parameters/CategoryParam"},{"$ref":"#/components/parameters/TagParam"},{"$ref":"#/components/parameters/UpdatedAfterParam"}],"responses":{"200":{"description":"Published item summaries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicItemListResponse"}}}}}}},"/api/public/items/{slug}":{"get":{"tags":["Public API"],"summary":"Get published item detail","parameters":[{"$ref":"#/components/parameters/ItemSlugParam"},{"$ref":"#/components/parameters/LocaleParam"}],"responses":{"200":{"description":"Published item detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicItemDetail"}}}},"404":{"description":"Item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}}}}}},"/api/public/taxonomies":{"get":{"tags":["Public API"],"summary":"List public taxonomies","parameters":[{"$ref":"#/components/parameters/TaxonomyTypeParam"},{"$ref":"#/components/parameters/StatusParam"}],"responses":{"200":{"description":"Taxonomy list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicTaxonomyListResponse"}}}}}}},"/api/public/updates":{"get":{"tags":["Public API"],"summary":"List directory updates","parameters":[{"$ref":"#/components/parameters/LocaleParam"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"Update feed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicUpdatesResponse"}}}}}}},"/agent.json":{"get":{"tags":["Discovery"],"summary":"Agent discovery manifest","description":"Returns AI-agent-oriented discovery metadata, public resources, and citation policy.","responses":{"200":{"description":"Agent manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentManifest"}}}}}}},"/.well-known/agent.json":{"get":{"tags":["Discovery"],"summary":"Well-known agent discovery manifest","description":"Alias of /agent.json for clients that probe standard well-known discovery locations.","responses":{"200":{"description":"Well-known agent manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentManifest"}}}}}}},"/feed.json":{"get":{"tags":["Discovery"],"summary":"JSON Feed updates stream","description":"Returns a JSON Feed 1.1 stream for recent published updates.","parameters":[{"$ref":"#/components/parameters/LocaleParam"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"JSON Feed 1.1 response","content":{"application/feed+json":{"schema":{"$ref":"#/components/schemas/JsonFeed"}},"application/json":{"schema":{"$ref":"#/components/schemas/JsonFeed"}}}}}}}}}