Base URL: https://byagents.dev. Authentication: none for these public knowledge endpoints. Contract: OpenAPI JSON. Version: 1.1.0. The API returns this site’s documentation; it does not run product diagnostics or search third-party businesses.
Search
GET /api/knowledge/search accepts q, limit, and audience. q is required, trimmed, and limited to 200 characters. limit defaults to 5 and must be an integer from 1 through 20. audience, if supplied, must be humans or agents. Unknown parameters are rejected. Repeated parameters are rejected to avoid ambiguous interpretation.
curl 'https://byagents.dev/api/knowledge/search?q=crawl%20access&limit=3&audience=humans'A successful JSON response contains version, query, total, and results. Each result includes id, title, description, audience, category, updated, url, markdown_url, and excerpt. total is the number of matching documents before the limit. Empty matches return HTTP 200 with total 0 and an empty results array.
Matching behavior
Search normalizes case and accents, removes common query words, and uses token matches across titles, descriptions, categories, and body text. Titles and descriptions carry more weight than body occurrences. Ranking is relevance within this finite library, not a quality grade for companies. Ties are resolved by document identifier for consistent output.
Index and documents
GET /api/knowledge/index returns version, updated, total, and documents containing public metadata and canonical representation URLs. It omits full body text. Markdown lives at /content/{audience}/{slug}.md. Unknown documents return HTTP 404. The full export is /llms-full.txt.
Errors and methods
Invalid search parameters return HTTP 400 with error.code = invalid_query and a readable error.message. Unsupported methods return HTTP 405. Public JSON endpoints allow cross-origin GET requests and expose read-only OPTIONS responses. No endpoint accepts credentials, private documents, mutations, payments, or uploads.
Freshness and operational limits
Search responses may be cached for 60 seconds; index, facts, and text responses for 300 seconds, with additional stale-while-revalidate time. The service publishes no uptime guarantee or unlimited request allowance. Fetch focused documents, reuse responses when appropriate, and back off on HTTP 429 or 5xx according to the response. Do not send secrets in query strings.
Document selection metadata
Index and search metadata also include level, outcome, and published. level is Business, Technical, or Mixed; it describes assumed reader background, not product maturity. outcome describes what the document helps the reader produce or decide. published records the original publication date; updated records the editorial review date. Neither is a real-time upstream monitoring timestamp.