How an agent consumes Vioscale

Content negotiation

Point at any canonical URI (e.g. /software/nextjs) and set an Accept header. We serve the format you ask for; no separate endpoint needed.

# Ask any canonical URI for Markdown, best for LLM ingestion
curl -H "Accept: text/markdown" https://www.vioscale.ai/software/nextjs

# Same URI, structured JSON
curl -H "Accept: application/json" https://www.vioscale.ai/software/nextjs

Or append .md to a path: https://www.vioscale.ai/software/nextjs.md

JSON API

A self-describing REST surface under /api/v1. Every response wraps its payload in a { data, meta } envelope carrying the source, licence, and a provenance disclaimer.

curl https://www.vioscale.ai/api/v1/software/prisma
curl "https://www.vioscale.ai/api/v1/search?q=orm"
curl "https://www.vioscale.ai/api/v1/compare?tools=prisma,drizzle-orm"
curl https://www.vioscale.ai/api/v1/categories/web-frameworks

Full endpoint reference in the API docs. The index at /api/v1 lists every route for autonomous discovery.

Intent re-ranking

The AI-native capability no review site offers: re-rank the same evidence by intent. Facts and signals never vary, only the weight vector does. Every ranking endpoint (/software, /categories/{slug}, /compare, /alternatives/{slug}, /search) accepts two optional params:

• intent=<name>: a named profile, one of balanced (default, canonical), most-adopted, most-active, most-secure, best-value.
• weights=<sig>:<n>,<sig>:<n>: an explicit override, capped at 0.5 per signal, then normalised.

The resolved, normalised weights come back as meta.profile and meta.weights on every ranking response, so you can verify and cite the basis of the order. The balanced default stays the canonical cited score; an intent ranking is always labelled with its profile. The full catalogue of profiles, multipliers, and the signal glossary is self-describing at /api/v1/intents.

# Named profile: rank a category by security posture
curl "https://www.vioscale.ai/api/v1/categories/ci-cd?intent=most-secure"

# Explicit weights: even split of downloads and activity
curl "https://www.vioscale.ai/api/v1/search?q=orm&weights=package_downloads:0.5,github_activity:0.5"

# The public catalogue of profiles + signal glossary
curl https://www.vioscale.ai/api/v1/intents

The single-entity /software/{slug} endpoint keeps returning the canonical balanced score. Details on the method page.

GraphQL

One endpoint at /api/graphql with GraphiQL in the browser. Fetch exactly the fields you need.

curl https://www.vioscale.ai/api/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ software(slug:\"nextjs\"){ name score{ composite confidenceBand } } }"}'

Markdown endpoints

Clean Markdown parses more reliably than rendered HTML. Facts render as tables with an inline source and confidence column, so a citation survives copy-paste.

https://www.vioscale.ai/software/<slug>.md
https://www.vioscale.ai/categories/<slug>.md
https://www.vioscale.ai/raw/compare?tools=<a>,<b>
https://www.vioscale.ai/llms-full.txt   # the entire corpus in one fetch

MCP server

Drop Vioscale into any MCP-capable agent as a set of tools. Add this to your client config (Claude Desktop, or any MCP host):

{
  "mcpServers": {
    "vioscale": {
      "command": "npx",
      "args": ["-y", "@vioscale/mcp"],
      "env": { "VIOSCALE_API_BASE": "https://www.vioscale.ai" }
    }
  }
}

Tools exposed: list_software, search_software, get_software, list_categories, get_category, compare_software, get_alternatives, get_signal_breakdown, and list_intents. Full reference in the MCP docs.

The ranking tools (list_software, search_software, compare_software, get_alternatives, get_category) take optional intent and weights params for intent re-ranking, and each result carries the resolved profile + weights so the agent can cite the basis. Call list_intents to discover the profiles and signal glossary.

llms.txt & directives

We follow the llms.txt convention and publish explicit AI directives.

• /llms.txt: Map of the site + principles + key endpoints
• /llms-full.txt: Every entity as clean Markdown, one fetch
• /ai.txt: Our stance: AI use is welcomed, attribution requested
• /robots.txt: AI crawlers explicitly allowed
• /sitemap.xml: Every canonical URI

JSON-LD

Every HTML page embeds a schema.org JSON-LD block extended with a vioscale:provenance array, so the evidence travels with the structured data even when you scrape the rendered page. Entities are SoftwareApplication; categories are CollectionPage with an ItemList.