Skip to main content

AI Resources

This page describes how AI agents interact with ZeyOS and lists the statically hosted, machine-readable documentation surface.

Start here​

  • /llms.txt - the agent entrypoint: how to authenticate, query, which client to use, and where the specs live.
  • /.well-known/llms.txt - alias (same content as /llms.txt).
  • /ai/manifest.json - stable artifact manifest (sha256 + bytes; offline-safe).
  • /ai/index.json - same artifact list plus a build timestamp (generatedAt).

How an agent connects to ZeyOS​

ZeyOS data lives behind a per-instance REST API. An agent connects like this:

  1. Authenticate - obtain an OAuth2 bearer token from https://cloud.zeyos.com/{INSTANCE}/auth/v1/ (see the Authentication API).
  2. Query - POST to https://cloud.zeyos.com/{INSTANCE}/api/v1/{resource}/ with a JSON body (fields, filters, sort, limit, expand, count). See the REST API introduction.
  3. Use the official client - for most agent and scripting work, use @zeyos/client and the zeyos CLI instead of hand-rolling HTTP. The client, CLI, agent quickstart, and recipes live under API Guide.

/llms.txt contains the full version of this flow, a copy-paste curl example, the client snippet, and the query-model gotchas - point your agent there first.

Connecting clients​

Machine-readable specs (mirrored when available)​

Canonical source-of-truth is https://cloud.zeyos.com/__doc/.... These are mirrored onto this docs host during build (when available) to reduce cross-domain friction.

  • REST OpenAPI: /__doc/openapi/api.json (alias: /openapi.json)
  • OAuth2 OpenAPI: /__doc/openapi/oauth2.json (alias: /openapi.oauth2.json)
  • Database reference: /__doc/dbref.json (alias: /dbref.json)
  • iXML reference: /__doc/ixmldoc.xml (alias: /ixmldoc.xml)

Derived, chunked indexes​

  • OpenAPI tags: /ai/openapi/tags.json (per-tag Markdown + per-tag OpenAPI slice JSON URLs)
  • OpenAPI operations: /ai/openapi/operations.json (method/path + tag links)
  • DB tables/views: /ai/db/tables.json (per-entity Markdown + per-entity JSON URLs)
  • DB relations graph: /ai/db/relations.json (foreign-key edges list)
  • iXML namespaces: /ai/ixml/namespaces.json (per-namespace Markdown URLs)

Bundles (optional, for RAG)​

  • /llms-full.txt - one-shot, high-signal working set (plain text)
  • /ai/docs.jsonl - NDJSON bundle (one JSON record per chunk; each record contains full text)
  • /ai/docs.jsonl.gz - gzip-compressed NDJSON bundle
  • /ai/download/zeyos-ai-docs.tar.gz - deterministic single-download bundle for offline ingestion

Contract, change detection & caching​

  • The paths listed in /ai/manifest.json are treated as the public contract.
  • /ai/index.json is the same artifact list but includes generatedAt and changes every build.
  • Cache artifacts by sha256 + bytes to avoid re-ingesting unchanged content.
  • If an AI-surface URL must change, ZeyOS keeps an alias copy for a deprecation window (no silent removals).

Inclusion / redaction​

  • This surface contains technical reference docs only (OpenAPI, DB reference, iXML reference + derived indexes).
  • It does not include tenant/customer data. Examples are documentation-only.

Locale notes​

  • English is served at /…
  • German is served under /de/… (e.g. /de/llms.txt, /de/ai/manifest.json)

Usage examples (integration-focused)​

Set BASE_URL once (replace with your docs host):

Bash
export BASE_URL="https://www.zeyos.com"

Fetch the agent entrypoint:

Bash
curl -sS "$BASE_URL/llms.txt"

Find an endpoint and then fetch its tag slice:

Bash
curl -sS "$BASE_URL/ai/openapi/operations.json" | jq '.operations[] | select(.path=="/accounts/{ID}" and .method=="GET")'
curl -sS "$BASE_URL/ai/openapi/tag.accounts.openapi.json"

Fetch a DB table definition as JSON (schema + constraints/indexes + inbound refs):

Bash
curl -sS "$BASE_URL/ai/db/table.accounts.json"

Download the full deterministic bundle for offline/RAG ingestion:

Bash
curl -L -o zeyos-ai-docs.tar.gz "$BASE_URL/ai/download/zeyos-ai-docs.tar.gz"

Maintainers​

  • Validate AI surface: npm run verify:ai-docs
  • Full build + link check: npm run verify