# Publishing contract and representation map

> Stable URLs, canonical identity, content types, search scope, caching, and maintenance.

Canonical: https://byagents.dev/agents/publishing-contract
Published: 2026-09-13
Reviewed: 2026-09-13
Publisher: ByAgents
Type: Reference
Level: Technical
Outcome: Understand the exact representations and behavior this library publishes.

This website is designed to be usable through ordinary HTTP requests as well as a browser. Public information does not require an installed plugin, an API key, or a paid account. The separate product preview can have different access requirements.

## Representation map
| Resource | URL | Representation |
| --- | --- | --- |
| Human guide | /humans/{slug} | HTML |
| Agent reference | /agents/{slug} | HTML |
| Individual document | /content/{audience}/{slug}.md | Markdown |
| Library index | /api/knowledge/index | JSON |
| Library search | /api/knowledge/search?q={query} | JSON |
| Product facts | /agents/facts.json | JSON |
| API description | /agents/openapi.json | OpenAPI JSON |
| Concise agent index | /llms.txt | Plain text Markdown |
| Complete library | /llms-full.txt | Plain text Markdown |
| Public page inventory | /sitemap.xml | XML |

The placeholders above denote path variables, not literal valid URLs. Use the index response for exact document URLs.

## One content source
HTML, Markdown, the full export, and search all use the same checked-in content records. Each record has a stable slug, audience, title, description, category, kind, body, sources, related documents, and updated date. Machine representations do not contain hidden product claims absent from the visible pages.

## Canonical identity
Canonical page URLs use https://byagents.dev. Markdown responses identify their canonical HTML page in both the text and a Link response header. Search results use those same URLs. Search result pages are not intended as independently indexed editorial pages.

## Response behavior
Documents are UTF-8. Missing records return 404. Invalid search parameters return 400. Public knowledge endpoints are read-only and support cross-origin GET requests. Cache lifetimes are documented in the API reference. There is no authentication token to discover or embed.

## Changes
Content revisions update the relevant record’s review date. URLs should remain stable when wording changes; a renamed document should receive an appropriate redirect. Breaking API changes require a new declared contract version. This is a publishing policy, not an uptime or backward-compatibility guarantee.

## Scope
The library explains discovery and publishes its own knowledge interfaces. It does not fetch arbitrary customer URLs, accept uploads, execute code, or perform transactions. No visit or retrieval alone is reported as a business outcome.

## Related reading

- [Knowledge API: requests and responses](https://byagents.dev/agents/knowledge-api)
- [Evidence, editorial policy, and trust boundaries](https://byagents.dev/agents/evidence-policy)
- [Start here: retrieve, verify, cite](https://byagents.dev/agents/start)