{"schemaVersion":1,"title":"Full-text search and agent JSON API","url":"https://appgram.github.io/docsy/versions/current/fr/guides/tutorials/search-and-agents","markdownUrl":"https://appgram.github.io/docsy/format-md/versions/current/fr/guides/tutorials/search-and-agents","jsonUrl":"https://appgram.github.io/docsy/agent/pages/versions/current/fr/guides/tutorials/search-and-agents.json","version":"current","locale":"fr","markdown":"# Full-text search and agent JSON API\n\nSearch complete content and retrieve permission-aware JSON or Markdown for coding agents.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nDocsy exposes the same authored guides, API reference, and SDK content to people and software. Browser search and the JSON query API share an index and ranking implementation.\n\n## Full-text search\n\nSearch includes article paragraphs, code examples, rich-component content, API parameters, and SDK symbol content. Matches in titles rank ahead of body matches. Multiple query terms must all occur in the indexed section; accent differences are normalized.\n\n```yaml\nsearch:\n  enabled: true\n  maxResults: 30\n```\n\nArticle results link to the matching section and show a text excerpt. Search follows the reader's selected version and locale. Locked sites filter the index by documentation permissions before returning it. Search is local text retrieval, not semantic or generative AI search.\n\nQueries match words, with prefix completion on the final term. Translated-context fallback records identify their actual `contentLocale` and `isFallback` status, so an agent can distinguish the requested locale from the language of the returned article.\n\n## Static JSON and Markdown exports\n\nThese work on GitHub Pages and other static hosts:\n\n| Resource | Purpose |\n| --- | --- |\n| `/agent/index.json` | Versioned full-text records and retrieval links |\n| `/agent/pages/guides/getting-started.json` | A page's title, canonical URL, context, and Markdown |\n| `/format-md/guides/getting-started` | The same page as clean Markdown |\n| `/llms.txt` | Discover documentation and machine-readable links |\n| `/llms-full.txt` | Combined readable documentation |\n\nAdd `site.basePath` before each path. For this portal the prefix is `/docsy`. The overview document uses the key `index`, such as `/agent/pages/index.json`.\n\nNon-default contexts include their route prefix in the document key: `/agent/pages/versions/v1/fr/guides/getting-started.json`.\n\n```yaml\nagent:\n  enabled: true\n  query: false\n  maxResults: 10\n  maxQueryLength: 500\n```\n\nAn agent on static hosting downloads the index, performs local retrieval, and follows each record's `jsonUrl` or `markdownUrl`. Static hosts cannot execute a `q` parameter. The query endpoint explicitly reports this limitation rather than returning pretend query results.\n\n## Enable a live JSON query endpoint\n\n```yaml\nagent:\n  enabled: true\n  query: true\n  maxResults: 10\n  maxQueryLength: 500\n```\n\n`agent.query: true` switches the build to the standalone server, even when documentation access is open. Deploy on Node, Bun, or Docker, not GitHub Pages. Build with Node 22.22 or newer; the production process can use Node or Bun 1.3.5 or newer (`npm run start:bun`).\n\n```bash\ncurl 'https://docs.example.com/docs/agent/query.json?q=authentication&version=current&locale=en&type=page&limit=5'\n```\n\n`q` is required. `version` and `locale` default to the configured defaults. `type` can be `page`, `api`, or `sdk`; omit it to search all three. `limit` must be between one and `agent.maxResults`.\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"query\": \"authentication\",\n  \"version\": \"current\",\n  \"locale\": \"en\",\n  \"count\": 1,\n  \"results\": [\n    {\n      \"title\": \"Authentication\",\n      \"url\": \"https://docs.example.com/docs/guides/getting-started#authentication\",\n      \"jsonUrl\": \"https://docs.example.com/docs/agent/pages/guides/getting-started.json\",\n      \"markdownUrl\": \"https://docs.example.com/docs/format-md/guides/getting-started\",\n      \"excerpt\": \"Configure the authentication scheme required by your API…\",\n      \"score\": 58,\n      \"version\": \"current\",\n      \"locale\": \"en\",\n      \"type\": \"page\"\n    }\n  ]\n}\n```\n\nThis is retrieval, not an LLM answer: it does not need a provider key, make external AI calls, execute examples, or accept file paths to read. Your agent can cite the returned URLs and fetch the matching JSON or Markdown document. Invalid parameters return 400. The runtime endpoint limits callers to 60 valid queries per minute per server-observed client address; deployments behind proxies should also enforce limits at their trusted edge.\n\n## Permissions and content negotiation\n\nLocked sites apply the existing documentation rules to JSON documents, Markdown exports, search results, and combined discovery files. Private responses are not shared-cacheable. Variant URLs inherit canonical page rules, so `/guides/private` remains protected in every version and locale.\n\nWhen running the Node or Bun server, a known documentation URL also supports `Accept: text/markdown`. Static deployments use the explicit export paths instead. Credentials and tier identities still come from your trusted proxy or configured authorization webhook.\n\n","contentLocale":"en","isFallback":true,"authorship":{"authors":[{"name":"nedimf","kind":"human","github":"nedimf","avatar":"/docsy/assets/authors/nedimf.png","role":"AppGram","id":"nedimf","url":"https://github.com/nedimf"},{"name":"AppGram","kind":"organization","github":"AppGram","url":"https://appgram.dev","avatar":"/docsy/assets/ag-logo.svg","id":"appgram"}],"contributors":[],"reviewedBy":[]},"editUrl":"https://github.com/AppGram/docsy/edit/main/content/tutorials/search-and-agents.md"}