Developers & Agents

Stable machine-readable access for search systems, copilots, and AI agents

Opstt exposes a public catalog API, an OpenAPI contract, an LLM guidance file, a JSON Feed, and an agent manifest so external systems can retrieve tool data without scraping rendered pages.

Try the AI agent OpenAPI spec Public API index

Public API Index

Discovery entrypoint with stable links, policies, and endpoint examples.

https://opstt.com/api/public

OpenAPI Specification

Typed contract for public items, taxonomies, updates, feed, and discovery surfaces.

https://opstt.com/openapi.json

LLMs Guide

Canonical crawling, citation, and retrieval guidance for language models.

https://opstt.com/llms.txt

Agent Manifest

Primary AI-agent discovery manifest with capabilities, resources, and citation policy.

https://opstt.com/agent.json

Well-Known Manifest

Alias for agents that probe standard well-known discovery locations first.

https://opstt.com/.well-known/agent.json

Updates Feed

JSON Feed 1.1 stream for monitoring directory changes and release-like updates.

https://opstt.com/feed.json?locale=fr&limit=20

GEThttps://opstt.com/api/public

API index

Bootstrap endpoint discovery, policy reading, and example URL acquisition.

• Stable starting point for agents and external integrations.
• Includes cache, crawl, freshness, evidence, and error semantics.

GEThttps://opstt.com/api/public/items?locale=fr&page=1&limit=20&featured=true&updated_after=2026-01-01T00:00:00.000Z

Item list

Search, ranking, pagination, filtering, and shortlist generation.

• locale falls back to the default locale when unsupported.
• limit is clamped to 50.

GEThttps://opstt.com/api/public/items/%7Bslug%7D?locale=fr

Item detail

Retrieve full listing content, alternates, FAQ, attributes, trust signals, freshness, and evidence.

• Returns `404` with a stable error payload when a published localized item is missing.
• Canonical localized page URLs should be used for end-user citation.

GEThttps://opstt.com/api/public/updates?locale=fr&limit=20

Updates

Detect item changes and refresh candidates before hydrating detail pages.

• Prefer this or the JSON Feed for recrawl scheduling.
• Use together with freshness.lastChangedAt for selective refetching.

Recommended integration order

Read /agent.json or /.well-known/agent.json for discovery metadata.
Load /openapi.json if your client supports typed planning or schema validation.
Start from /api/public for a stable endpoint map and policy surface.
Use /api/public/items for summaries and hydrate individual records from /api/public/items/{slug}.
Use /feed.json or /api/public/updates to detect change events before recrawling item detail.

Cache and indexing policy

Machine-readable responses send public, max-age=300, s-maxage=3600, stale-while-revalidate=86400 with X-Robots-Tag: noindex, follow.
Respect response Cache-Control headers and use /feed.json or /api/public/updates as the preferred recrawl trigger surfaces.
Browser TTL is 300s, shared cache TTL is 3600s, and stale-while-revalidate is 86400s.

Error semantics

Public list endpoints prefer normalization over hard failure for unsupported query values. Item detail remains strict for missing published localized records and returns a stable 404 contract.

Unsupported locale values fall back to the default locale.
limit is clamped to a maximum of 50 and falls back to the default when invalid.
Unknown taxonomy type values fall back to category for /api/public/taxonomies.

404 payload

{
  "status": 404,
  "error": "not_found",
  "message": "Published item not found for this locale."
}

Freshness and evidence semantics

For AI retrieval and agent workflows, the fastest way to rank record quality is to combine freshness, evidence, and trustSignals instead of relying only on raw descriptions.

Freshness tracks publication, localized content changes, record updates, enrichment, manual review cadence, and recrawl hints.
Evidence tracks whether the item has an official source, manual review, structured attributes, and written content.
trustSignals remains the detailed fact surface for pricing, integrations, platforms, regions, languages, and verification notes.

Example requests

List featured items updated after a checkpoint

curl -s 'https://opstt.com/api/public/items?locale=fr&page=1&limit=20&featured=true&updated_after=2026-01-01T00:00:00.000Z'

Hydrate one localized item detail

curl -s 'https://opstt.com/api/public/items/%7Bslug%7D?locale=fr'

Poll the JSON Feed for change detection

curl -s 'https://opstt.com/feed.json?locale=fr&limit=20'

Example response shapes

List response excerpt

{
  "apiVersion": "2026-03-08",
  "locale": "fr",
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 124,
    "totalPages": 7
  },
  "items": [
    {
      "slug": "example-tool",
      "title": "Example Tool",
      "publicUrl": "https://opstt.com/items/example-tool",
      "updatedAt": "2026-03-01T12:00:00.000Z",
      "freshness": {
        "lastChangedAt": "2026-03-02T09:00:00.000Z",
        "publishedAt": "2026-02-10T08:00:00.000Z",
        "contentUpdatedAt": "2026-03-01T12:00:00.000Z",
        "recordUpdatedAt": "2026-03-01T12:00:00.000Z",
        "enrichedAt": "2026-03-02T09:00:00.000Z",
        "reviewedAt": "2026-03-03T10:00:00.000Z",
        "recommendedReviewWindowDays": 30,
        "reviewDueAt": "2026-04-02T10:00:00.000Z",
        "recrawlHints": [
          "manual_review_available",
          "official_source_available"
        ]
      },
      "evidence": {
        "basisLevel": "verified",
        "officialSourceUrl": "https://example.com",
        "sourceHost": "example.com",
        "officialSourceAvailable": true,
        "manualReviewAvailable": true,
        "structuredAttributesAvailable": true,
        "writtenContentAvailable": true,
        "evidenceSummary": "official vendor site + manual review + structured attributes",
        "evidenceSources": [
          "official vendor site",
          "manual review",
          "structured attributes"
        ]
      }
    }
  ]
}

Detail response excerpt

{
  "slug": "example-tool",
  "canonicalUrl": "https://opstt.com/items/example-tool",
  "alternates": {
    "languages": {
      "en": "https://opstt.com/items/example-tool",
      "zh": "https://opstt.com/zh/items/example-tool-cn"
    }
  },
  "freshness": {
    "lastChangedAt": "2026-03-03T10:00:00.000Z",
    "reviewDueAt": "2026-04-02T10:00:00.000Z"
  },
  "evidence": {
    "basisLevel": "verified",
    "evidenceSummary": "official vendor site + manual review + structured attributes"
  },
  "trustSignals": {
    "sourceHost": "example.com",
    "reviewedAt": "2026-03-03T10:00:00.000Z",
    "contentUpdatedAt": "2026-03-01T12:00:00.000Z",
    "recordUpdatedAt": "2026-03-01T12:00:00.000Z",
    "evidenceSources": [
      "official vendor site",
      "manual review",
      "structured attributes"
    ]
  }
}

Quick-start patterns

Catalog ingestion

Start from /api/public, fetch /api/public/items, then hydrate individual records from /api/public/items/{slug}.

Locale-aware retrieval

Use the detail endpoint alternates object to map localized slugs and canonical URLs across languages.

Change monitoring

Poll /feed.json or /api/public/updates first, then re-fetch item detail only when freshness.lastChangedAt changes.

Trust-aware ranking

Use evidence.basisLevel, trustSignals, and freshness.reviewDueAt together to separate stronger records from thin or aging listings.

Freshness fields

lastChangedAt: Most recent meaningful change timestamp across manual review, enrichment, content refresh, and record updates.
publishedAt: First public publication timestamp. Falls back to createdAt when no explicit publication date exists.
contentUpdatedAt: Last update timestamp for localized editorial content when available.
recordUpdatedAt: Last update timestamp for the underlying published directory record.
enrichedAt: Last automated enrichment timestamp for directory fact refresh, if available.
reviewedAt: Last manual review timestamp, if available.
recommendedReviewWindowDays: Suggested operational review window used to derive reviewDueAt. Featured items skew shorter than basic listings.
reviewDueAt: Operational re-review target derived from the most recent manual review and review window. It is not a guaranteed recrawl time.
recrawlHints: Machine-readable hints that indicate which freshness signals are present or missing for a listing.

Evidence fields

basisLevel: verified means official source plus manual review; mixed means at least one stronger evidence layer exists; basic means only directory-level metadata is available.
officialSourceAvailable: Whether the listing records a public official vendor URL. It does not guarantee a live source-health probe succeeded at response time.
manualReviewAvailable: Whether the listing has a recorded manual review timestamp.
structuredAttributesAvailable: Whether the listing exposes structured attribute data that can support filtering or ranking.
writtenContentAvailable: Whether the listing exposes editorial description or content beyond raw directory metadata.
evidenceSources: Human-readable summary of the evidence layers currently present for the item.
evidenceSummary: Short combined summary of the item evidence basis for ranking or review workflows.

Source health policy

Recorded vendor URLs improve evidence quality, but they are not the same thing as a live availability probe. Use source health checks to detect parked domains, unrelated redirects, and broken brand assets before trusting time-sensitive claims.

recordedUrlVsLiveProbe: officialSourceAvailable means a vendor URL is recorded for the listing. It is not a promise that the URL passed a live availability probe during this API response.
recommendedChecks: Run operational checks for official URL availability, redirect destination safety, parked-domain detection, favicon health, and primary brand asset health.
degradePolicy: If a recorded source becomes unreachable, parked, or redirects to an unrelated domain, queue manual review and treat time-sensitive claims as stale until re-verified.

Versioning and stability

Strategy: additive-first
Breaking changes: Breaking changes should be announced through /developers and /openapi.json before rollout.
Existing top-level fields should remain stable whenever possible.
New fields may be added without a version bump when changes are backward-compatible.
Consumers should ignore unknown fields to remain forward-compatible.

Prefer these sources

Canonical pages: localized URLs from sitemap and item detail alternates.
Automation: /api/public and /openapi.json.
Agent bootstrap: /agent.json and /.well-known/agent.json.
Recrawl triggers: /feed.json and /api/public/updates.