--- schema: formation.doc/v0.1 kind: doc visibility: public canonical_url: https://topologyindex.com/docs/api/routes.md path: /docs/api/routes.md product_api_version: v1 routes: - access: public method: GET path: / - access: public method: GET path: /llms.txt - access: public method: GET path: /robots.txt - access: public method: GET path: /sitemap.txt - access: public method: GET path: /indexnow.txt - access: public method: GET path: /.well-known/mcp-registry-auth - access: public method: GET path: /.well-known/glama.json - access: public method: GET path: /.well-known/agent-card.json - access: public method: GET path: /.well-known/agent.json - access: public method: GET path: /.well-known/mcp/server-card.json - access: public method: GET path: /.well-known/mcp.json - access: public method: GET path: /.well-known/ard.json - access: public method: GET path: /.well-known/ai-catalog.json - access: public method: GET path: /.well-known/mcp - access: public method: GET path: /.well-known/mcp-server-card - access: public method: GET path: /.well-known/mcp/server-cards.json - access: public method: GET path: /.well-known/owners.json - access: public method: GET path: /mcp/.well-known/owners.json - access: public method: GET path: /docs/index.md - access: public method: GET path: '/docs/schemas/{kind}/{version}.md' - access: public method: GET path: /patterns/index.md - access: public method: GET path: '/patterns/{pattern}.md' - access: public method: GET path: '/patterns/{pattern}/findings.md' - access: public method: GET path: /domains/index.md - access: public method: GET path: '/domains/{domain}.md' - access: public method: GET path: '/domains/{domain}/findings.md' - access: public method: GET path: /guides/agentic-design-patterns.md - access: public method: GET path: /research/index.md - access: public method: GET path: '/research/{source}.md' - access: public method: GET path: /formations/index.md - access: public method: GET path: /starters/index.md - access: public method: GET path: '/starters/{name}/{version}.md' - access: public method: GET path: '/formations/{publisher}/{name}/{version}.md' - access: public method: GET path: '/artifacts/sha256/{digest}.md' - access: public method: GET path: '/artifacts/sha256/{digest}/signature.md' - access: public method: GET path: '/artifacts/sha256/{digest}/status.md' - access: public method: GET path: /trust/keys.md - access: public method: GET path: /status.md - access: public method: POST path: /mcp - access: 'use ticket' method: POST path: /v1/use-receipts - access: artifacts:read method: GET path: T/formations/index.md - access: artifacts:read method: GET path: T/execution-locks/index.md - access: formations:write method: POST path: T/formations - access: formations:write method: POST path: T/execution-locks - access: evaluations:plan method: POST path: T/workload-profiles - access: evaluations:plan method: POST path: T/suites - access: artifacts:read method: GET path: 'T/artifacts/sha256/{digest}.md' - access: artifacts:read method: GET path: 'T/artifacts/sha256/{digest}/signature.md' - access: artifacts:read method: GET path: 'T/artifacts/sha256/{digest}/status.md' - access: recommendations:read method: POST path: T/recommendations - access: evaluations:plan method: POST path: T/evaluation-plans - access: evaluations:start method: POST path: T/evaluations - access: evaluations:read method: GET path: 'T/evaluations/{job_id}.md' - access: evaluations:cancel method: POST path: 'T/evaluations/{job_id}/cancel' - access: 'runner credential' method: POST path: T/runner/claims - access: 'runner credential' method: POST path: T/runner/heartbeats - access: 'runner credential' method: POST path: T/runs - access: artifacts:read method: GET path: T/evidence/index.md - access: adoptions:write method: POST path: T/adoptions - access: account:read method: GET path: T/account.md - access: events:read method: GET path: T/events.md schema_version: v0.1 tenant_prefix: '/v1/tenants/{tenant_id}' title: Routes --- # Routes `T` stands for `/v1/tenants/{tenant_id}`. Mutations require `Idempotency-Key`; a repeat with the same key and body returns the original response, a repeat with other content is 409 `idempotency_conflict`. Bodies are `text/markdown; charset=utf-8`. - `GET /` (public): Service introduction - `GET /llms.txt` (public): Discovery index - `GET /robots.txt` (public): Crawl rules and content signals - `GET /sitemap.txt` (public): Plain-text sitemap of public pages - `GET /indexnow.txt` (public): IndexNow ownership key - `GET /.well-known/mcp-registry-auth` (public): MCP Registry domain proof - `GET /.well-known/glama.json` (public): Glama listing ownership claim - `GET /.well-known/agent-card.json` (public): A2A agent card pointing to the MCP server - `GET /.well-known/agent.json` (public): A2A agent card compatibility alias - `GET /.well-known/mcp/server-card.json` (public): MCP directory compatibility card - `GET /.well-known/mcp.json` (public): MCP server card discovery - `GET /.well-known/ard.json` (public): Agentic Resource Discovery manifest - `GET /.well-known/ai-catalog.json` (public): AI Catalog manifest - `GET /.well-known/mcp` (public): MCP server card discovery alias - `GET /.well-known/mcp-server-card` (public): MCP server card discovery alias - `GET /.well-known/mcp/server-cards.json` (public): MCP server card discovery alias - `GET /.well-known/owners.json` (public): VerifyMCP owners document (no owners listed) - `GET /mcp/.well-known/owners.json` (public): VerifyMCP owners document for the MCP path - `GET /docs/index.md` (public): Contract directory - `GET /docs/schemas/{kind}/{version}.md` (public): Versioned schema reference - `GET /patterns/index.md` (public): Pattern vocabulary by family - `GET /patterns/{pattern}.md` (public): One organizational pattern - `GET /patterns/{pattern}/findings.md` (public): Published findings on one pattern, in words - `GET /domains/index.md` (public): Task domains: a way into the decision guide - `GET /domains/{domain}.md` (public): Patterns studied in one task domain - `GET /domains/{domain}/findings.md` (public): Published findings in one task domain, in words - `GET /guides/agentic-design-patterns.md` (public): Guide: agentic design patterns - `GET /research/index.md` (public): Research records - `GET /research/{source}.md` (public): One cited research record - `GET /formations/index.md` (public): Public catalog - `GET /starters/index.md` (public): Unvalidated starter formations (optional `?task_class=`) - `GET /starters/{name}/{version}.md` (public): One starter FORMATION.md to copy - `GET /formations/{publisher}/{name}/{version}.md` (public): Public topology formation version - `GET /artifacts/sha256/{digest}.md` (public): Exact public bytes - `GET /artifacts/sha256/{digest}/signature.md` (public): Detached signature receipt - `GET /artifacts/sha256/{digest}/status.md` (public): Current status - `GET /trust/keys.md` (public): Signing keys - `GET /status.md` (public): Health and limitations - `POST /mcp` (public): Stateless MCP (JSON-RPC over Streamable HTTP): reads, plus report_outcome on a use ticket - `POST /v1/use-receipts` (use ticket): Redeem a use ticket with one use receipt (limited rollout) - `GET T/formations/index.md` (artifacts:read): Private candidates - `GET T/execution-locks/index.md` (artifacts:read): Resolved configurations - `POST T/formations` (formations:write): Register a private candidate - `POST T/execution-locks` (formations:write): Register an execution lock - `POST T/workload-profiles` (evaluations:plan): Register a workload profile - `POST T/suites` (evaluations:plan): Register suite metadata - `GET T/artifacts/sha256/{digest}.md` (artifacts:read): Private artifact - `GET T/artifacts/sha256/{digest}/signature.md` (artifacts:read): Private signature receipt - `GET T/artifacts/sha256/{digest}/status.md` (artifacts:read): Private eligibility - `POST T/recommendations` (recommendations:read): Evidence-backed decision - `POST T/evaluation-plans` (evaluations:plan): Validate and quote a plan - `POST T/evaluations` (evaluations:start): Start an approved plan - `GET T/evaluations/{job_id}.md` (evaluations:read): Job status - `POST T/evaluations/{job_id}/cancel` (evaluations:cancel): Request cancellation - `POST T/runner/claims` (runner credential): Claim an assignment - `POST T/runner/heartbeats` (runner credential): Renew a lease - `POST T/runs` (runner credential): Submit a run summary - `GET T/evidence/index.md` (artifacts:read): Evidence snapshots - `POST T/adoptions` (adoptions:write): Record an adoption outcome - `GET T/account.md` (account:read): Entitlements and usage - `GET T/events.md` (events:read): Event feed