{ "openapi": "3.1.0", "info": { "title": "Can My Agent Use Catalog API", "version": "1.1.0", "summary": "Read-only compatibility catalog and evidence ledger.", "description": "Check whether a chat, desktop, or CLI agent product supports a capability. Every published answer links to public evidence. Unknown means not yet sufficiently sourced; it does not mean unsupported. Documentation evidence is not runtime certification." }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://canmyagentuse.com", "description": "Production catalog" } ], "externalDocs": { "description": "Methodology and evidence rules", "url": "https://canmyagentuse.com/methodology" }, "tags": [ { "name": "Catalog", "description": "Published capabilities, exact harness surfaces, and specifications." }, { "name": "Evidence", "description": "Coverage, source provenance, and support assertions." }, { "name": "Research", "description": "Proposed test definitions, changes, contradictions, and open questions." }, { "name": "Evidence Atlas", "description": "The full 2026-08-28 vendor, product, exact-surface, feature, source, and compatibility-cell research seed." }, { "name": "Operations", "description": "Minimal service health." } ], "paths": { "/api/v1/features.json": { "get": { "operationId": "listFeatures", "tags": [ "Catalog" ], "summary": "List published capabilities", "responses": { "200": { "description": "Published capability collection.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FeatureSummary" } } } } } } } } } }, "/api/v1/features/{slug}.json": { "get": { "operationId": "getFeature", "tags": [ "Catalog" ], "summary": "Get one capability with Markdown body", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Stable catalog slug.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "Capability record.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureDetail" } } } }, "404": { "description": "Unknown capability slug.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/harnesses.json": { "get": { "operationId": "listHarnesses", "tags": [ "Catalog" ], "summary": "List exact web, desktop, and CLI harness surfaces", "responses": { "200": { "description": "Published harness surface collection.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/HarnessSummary" } } } } } } } } } }, "/api/v1/harnesses/{slug}.json": { "get": { "operationId": "getHarness", "tags": [ "Catalog" ], "summary": "Get one exact harness surface with Markdown body", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Stable catalog slug.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "Harness surface record.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessDetail" } } } }, "404": { "description": "Unknown harness slug.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/specs.json": { "get": { "operationId": "listSpecifications", "tags": [ "Catalog" ], "summary": "List revision-aware specification and convention references", "responses": { "200": { "description": "Published specification reference collection.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SpecificationSummary" } } } } } } } } } }, "/api/v1/specs/{slug}.json": { "get": { "operationId": "getSpecification", "tags": [ "Catalog" ], "summary": "Get one specification reference with Markdown body", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Stable catalog slug.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "Specification reference.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecificationDetail" } } } }, "404": { "description": "Unknown specification slug.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/matrix.json": { "get": { "operationId": "getMatrix", "tags": [ "Evidence" ], "summary": "Get the current and version-track support matrix", "responses": { "200": { "description": "One cell per published capability and exact harness surface.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "cells" ], "properties": { "cells": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixCell" } } } } } } } } } }, "/api/v1/coverage.json": { "get": { "operationId": "getCoverage", "tags": [ "Evidence" ], "summary": "Get catalog research completeness", "description": "Counts sourced and explicit-unknown current-track cells. Coverage is not a product score.", "responses": { "200": { "description": "Coverage by total, surface, capability, and harness.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageReport" } } } } } } }, "/api/v1/evidence.json": { "get": { "operationId": "listEvidence", "tags": [ "Evidence" ], "summary": "List reviewed evidence and citing statements", "responses": { "200": { "description": "Evidence ledger with exact citing statements.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "evidenceClassNotice", "items" ], "properties": { "evidenceClassNotice": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceRecord" } } } } } } } } } }, "/api/v1/atlas.json": { "get": { "operationId": "getEvidenceAtlas", "tags": [ "Evidence Atlas" ], "summary": "Get the full exact-surface research index", "description": "Lists Atlas metadata, vendors, products, surfaces, atomic features, sources, registry entries, and proposed tests. Use the detail routes for compatibility cells.", "responses": { "200": { "description": "Evidence Atlas index and discovery document.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/atlas/surfaces/{slug}.json": { "get": { "operationId": "getEvidenceAtlasSurface", "tags": [ "Evidence Atlas" ], "summary": "Get all atomic compatibility cells for one exact surface", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Stable catalog slug.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "Exact surface, provider and product context, status counts, assertions, sources, and all feature cells.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/atlas/features/{slug}.json": { "get": { "operationId": "getEvidenceAtlasFeature", "tags": [ "Evidence Atlas" ], "summary": "Get one atomic feature across every exact surface", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Stable catalog slug.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "Atomic feature, status counts, assertions, sources, and all exact-surface cells.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/atlas/vendors/{slug}.json": { "get": { "operationId": "getEvidenceAtlasVendor", "tags": [ "Evidence Atlas" ], "summary": "Get one vendor and its exact research surfaces", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Stable catalog slug.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "Vendor inclusion basis, products, exact surfaces, and evidence-coverage counts.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/tests.json": { "get": { "operationId": "listConformanceTests", "tags": [ "Research" ], "summary": "List proposed conformance test definitions", "responses": { "200": { "description": "Proposed, not-run test registry.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/changes.json": { "get": { "operationId": "listChanges", "tags": [ "Research" ], "summary": "List relevant ecosystem change events", "responses": { "200": { "description": "Dated ecosystem change feed.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/contradictions.json": { "get": { "operationId": "listContradictions", "tags": [ "Research" ], "summary": "List evidence conflicts and open governance questions", "responses": { "200": { "description": "Contradiction and open-question ledger.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/health": { "get": { "operationId": "getHealth", "tags": [ "Operations" ], "summary": "Get service health", "responses": { "200": { "description": "Service is accepting requests.", "headers": { "Access-Control-Allow-Origin": { "description": "Public read-only catalog access.", "schema": { "type": "string", "const": "*" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "service" ], "properties": { "ok": { "type": "boolean", "const": true }, "service": { "type": "string", "const": "canmyagentuse" } } } } } } } } } }, "components": { "schemas": { "Status": { "type": "string", "enum": [ "yes", "partial", "no", "unknown", "na" ] }, "SupportStage": { "type": "string", "enum": [ "untracked", "requested", "planned", "experimental", "preview", "stable", "deprecated" ] }, "EvidenceType": { "type": "string", "enum": [ "documented", "tested", "vendor-attested", "listed", "reported", "inferred", "not-found" ] }, "Target": { "type": "object", "required": [ "kind", "revision" ], "properties": { "kind": { "type": "string", "enum": [ "release", "hosted-observation", "dated-documentation" ] }, "revision": { "type": "string" }, "observedAt": { "type": "string", "format": "date" } } }, "Qualifier": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "preview", "experimental", "plan", "policy", "region", "auth", "transport", "protocol-revision", "host-role", "feature-flag", "runtime", "vendor-extension", "origin-trial" ] }, "value": { "type": "string" } } }, "EvidenceReference": { "type": "object", "required": [ "resourceId", "type", "observedAt" ], "properties": { "resourceId": { "type": "string" }, "type": { "$ref": "#/components/schemas/EvidenceType" }, "observedAt": { "type": "string", "format": "date" } } }, "VersionCell": { "type": "object", "required": [ "track", "status", "noteIds" ], "properties": { "track": { "type": "string" }, "status": { "$ref": "#/components/schemas/Status" }, "noteIds": { "type": "array", "items": { "type": "integer" } }, "target": { "$ref": "#/components/schemas/Target" }, "environmentProfile": { "type": "string", "enum": [ "local-default", "hosted-default", "enterprise-managed", "preview-enabled", "air-gapped" ] }, "qualifiers": { "type": "array", "items": { "$ref": "#/components/schemas/Qualifier" } }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceReference" } }, "stage": { "$ref": "#/components/schemas/SupportStage" } } }, "SupportRow": { "type": "object", "required": [ "harness" ], "properties": { "harness": { "type": "string" }, "status": { "$ref": "#/components/schemas/Status" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/VersionCell" } } } }, "Resource": { "type": "object", "required": [ "title", "href", "kind" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "href": { "type": "string", "format": "uri-reference" }, "kind": { "type": "string", "enum": [ "docs", "spec", "note" ] }, "publisher": { "type": "string" }, "evidenceType": { "$ref": "#/components/schemas/EvidenceType" }, "reviewedAt": { "type": "string", "format": "date" }, "locator": { "type": "string" } } }, "FeatureSummary": { "type": "object", "required": [ "title", "slug", "summary", "support", "html", "markdown", "json" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "slug": { "type": "string" }, "locale": { "type": "string", "const": "en" }, "seoTitle": { "type": "string" }, "socialTitle": { "type": "string" }, "socialDescription": { "type": "string" }, "canonicalPath": { "type": "string" }, "previewImageAlt": { "type": "string" }, "llmSummary": { "type": "string" }, "audience": { "type": "string" }, "contentKind": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "updated": { "type": "string", "format": "date-time" }, "published": { "type": "string", "format": "date-time" }, "html": { "type": "string", "description": "Root-relative human-readable page." }, "markdown": { "type": "string", "description": "Root-relative Markdown twin generated from the same record." }, "json": { "type": "string", "description": "Root-relative JSON detail endpoint." }, "category": { "type": "string" }, "summary": { "type": "string" }, "specLabel": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "capabilityKind": { "type": "string", "enum": [ "atomic", "family" ] }, "parent": { "type": "string" }, "related": { "type": "array", "items": { "type": "string" } }, "relations": { "type": "array", "items": { "type": "object", "required": [ "feature", "type" ], "properties": { "feature": { "type": "string" }, "type": { "type": "string", "enum": [ "related", "requires", "extends", "alternative" ] }, "note": { "type": "string" } } } }, "highlight": { "type": "boolean" }, "notes": { "type": "array", "items": { "type": "object" } }, "issues": { "type": "array", "items": { "type": "object" } }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/Resource" } }, "support": { "type": "array", "items": { "$ref": "#/components/schemas/SupportRow" } } } }, "FeatureDetail": { "allOf": [ { "$ref": "#/components/schemas/FeatureSummary" }, { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string" } } } ] }, "HarnessSummary": { "type": "object", "required": [ "title", "slug", "family", "vendor", "surface", "summary", "html", "markdown", "json" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "slug": { "type": "string" }, "locale": { "type": "string", "const": "en" }, "seoTitle": { "type": "string" }, "socialTitle": { "type": "string" }, "socialDescription": { "type": "string" }, "canonicalPath": { "type": "string" }, "previewImageAlt": { "type": "string" }, "llmSummary": { "type": "string" }, "audience": { "type": "string" }, "contentKind": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "updated": { "type": "string", "format": "date-time" }, "published": { "type": "string", "format": "date-time" }, "html": { "type": "string", "description": "Root-relative human-readable page." }, "markdown": { "type": "string", "description": "Root-relative Markdown twin generated from the same record." }, "json": { "type": "string", "description": "Root-relative JSON detail endpoint." }, "family": { "type": "string" }, "vendor": { "type": "string" }, "surface": { "type": "string", "enum": [ "web", "desktop", "cli" ] }, "summary": { "type": "string" }, "tracks": { "type": "array", "items": { "type": "string" } }, "order": { "type": "integer" }, "homepage": { "type": "string", "format": "uri" }, "targetKind": { "type": "string", "enum": [ "release", "hosted-observation" ] }, "execution": { "type": "string", "enum": [ "local", "hosted" ] }, "defaultEnvironmentProfile": { "type": "string", "enum": [ "local-default", "hosted-default", "enterprise-managed", "preview-enabled", "air-gapped" ] } } }, "HarnessDetail": { "allOf": [ { "$ref": "#/components/schemas/HarnessSummary" }, { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string" } } } ] }, "SpecificationSummary": { "type": "object", "required": [ "title", "slug", "authority", "revision", "maturity", "summary", "html", "markdown", "json" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "slug": { "type": "string" }, "locale": { "type": "string", "const": "en" }, "seoTitle": { "type": "string" }, "socialTitle": { "type": "string" }, "socialDescription": { "type": "string" }, "canonicalPath": { "type": "string" }, "previewImageAlt": { "type": "string" }, "llmSummary": { "type": "string" }, "audience": { "type": "string" }, "contentKind": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "updated": { "type": "string", "format": "date-time" }, "published": { "type": "string", "format": "date-time" }, "html": { "type": "string", "description": "Root-relative human-readable page." }, "markdown": { "type": "string", "description": "Root-relative Markdown twin generated from the same record." }, "json": { "type": "string", "description": "Root-relative JSON detail endpoint." }, "authority": { "type": "string" }, "revision": { "type": "string" }, "maturity": { "type": "string" }, "structure": { "type": "string" }, "sourceId": { "type": "string" }, "canonicalUrl": { "type": "string", "format": "uri" }, "summary": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } }, "aliases": { "type": "array", "items": { "type": "string" } } } }, "SpecificationDetail": { "allOf": [ { "$ref": "#/components/schemas/SpecificationSummary" }, { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string" } } } ] }, "MatrixCell": { "type": "object", "required": [ "feature", "harness", "status", "versions" ], "properties": { "feature": { "type": "string" }, "harness": { "type": "string" }, "status": { "$ref": "#/components/schemas/Status" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/VersionCell" } } } }, "CoverageSlice": { "type": "object", "required": [ "total", "sourced", "unknown", "share" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "sourced": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 }, "share": { "type": "number", "minimum": 0, "maximum": 1 } } }, "CoverageReport": { "type": "object", "required": [ "generatedFrom", "totals", "surfaces", "features", "harnesses" ], "properties": { "generatedFrom": { "type": "string", "const": "published-current-track" }, "totals": { "allOf": [ { "$ref": "#/components/schemas/CoverageSlice" }, { "type": "object", "properties": { "features": { "type": "integer" }, "harnesses": { "type": "integer" } } } ] }, "surfaces": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/CoverageSlice" }, { "type": "object", "properties": { "surface": { "type": "string", "enum": [ "web", "desktop", "cli" ] }, "harnesses": { "type": "integer" } } } ] } }, "features": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/CoverageSlice" }, { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" } } } ] } }, "harnesses": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/CoverageSlice" }, { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "surface": { "type": "string", "enum": [ "web", "desktop", "cli" ] } } } ] } } } }, "EvidenceRecord": { "type": "object", "required": [ "id", "title", "href", "kind", "feature", "statements" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "href": { "type": "string", "format": "uri-reference" }, "kind": { "type": "string" }, "publisher": { "type": "string" }, "evidenceType": { "$ref": "#/components/schemas/EvidenceType" }, "reviewedAt": { "type": "string", "format": "date" }, "locator": { "type": "string" }, "feature": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" } } }, "statements": { "type": "array", "items": { "type": "object", "properties": { "harness": { "type": "string" }, "track": { "type": "string" }, "status": { "$ref": "#/components/schemas/Status" }, "observedAt": { "type": "string", "format": "date" } } } } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }