# ZeyOS for AI agents

ZeyOS is a business operating system (CRM, ERP, helpdesk, project and
groupware). Each customer runs an isolated instance, and business data is
read and written over a per-instance REST API. This file tells an agent how
to connect to that API, which client to use, and where the OpenAPI contract
and schema references live.

## Choose your task

The `zeyos` skill route "Use ZeyOS business data" is listed under "Use a coding agent with ZeyOS".

### Build a ZeyOS app

Write native iXML and Zymba that runs inside ZeyOS, and package it as an application.

Prerequisites: The ZeyOS SDK (zeysdk) and a linked sandbox instance; Permission to send source to that instance.

Read in this order:
1. Set up the SDK: /ixml/ixml-guide/development-environment/sdk#first-time-setup (Markdown: /ai/guide/ixml/ixml-guide/development-environment/sdk.md)
2. App structure: /ixml/ixml-guide/development-environment/app-structure (Markdown: /ai/guide/ixml/ixml-guide/development-environment/app-structure.md)
3. Execution contexts: /ixml/ixml-guide/development-environment/execution-contexts (Markdown: /ai/guide/ixml/ixml-guide/development-environment/execution-contexts.md)
4. Minimal app: /ixml/ixml-guide/development-environment/minimal-app (Markdown: /ai/guide/ixml/ixml-guide/development-environment/minimal-app.md)
5. Verification checkpoints: /ixml/ixml-guide/development-environment/verification-checkpoints (Markdown: /ai/guide/ixml/ixml-guide/development-environment/verification-checkpoints.md)

First success: You run `zeysdk compile` on the minimal app against your sandbox and it reports no errors. The published sample compiles on a sandbox but has not been run on an instance, so this run is your first evidence for your own instance.
Sample: Minimal app: /ixml/ixml-guide/development-environment/minimal-app
Troubleshooting: Native troubleshooting: /ixml/ixml-guide/development-environment/troubleshooting
Reference: /ixml, /zymba, /db, /sdk

### Connect an external application

Read and write ZeyOS data from a service, browser app or script running outside ZeyOS.

Prerequisites: Access to a ZeyOS instance; OAuth client credentials; Node.js 18 or later for the JavaScript client.

Read in this order:
1. Integration architecture: /guide/tutorials/integration-architecture (Markdown: /ai/guide/guide/tutorials/integration-architecture.md)
2. Authentication: /guide/api-reference/authentication (Markdown: /ai/guide/guide/api-reference/authentication.md)
3. JavaScript client: getting started: /guide/javascript-client/getting-started (Markdown: /ai/guide/guide/javascript-client/getting-started.md)
4. Making requests: /guide/javascript-client/making-requests (Markdown: /ai/guide/guide/javascript-client/making-requests.md)
5. Server-side integrations: /guide/tutorials/server-side-integrations (Markdown: /ai/guide/guide/tutorials/server-side-integrations.md)

First success: `client.schema.validate('listTickets', { fields: ['ID', 'name'] })` passes offline, then the same query returns your tickets.
Sample: Dashboard sample app (read-only): /guide/sample-apps/dashboard
Troubleshooting: Practical guide: /guide/javascript-client/practical-guide
Reference: /api, /auth, /db

### Use a coding agent with ZeyOS

Give a coding agent the authoritative references, project instructions and validation tools.

Prerequisites: A coding agent such as Kilo Code, Pi or OpenCode; The ZeyOS CLI and client, version 1.0.0 or later.

Read in this order:
1. Agent setup: /guide/agent-workflows/agent-setup (Markdown: /ai/guide/guide/agent-workflows/agent-setup.md)
2. Project instructions: /ai/agent-instructions.md
3. Agent quickstart: /guide/agent-workflows/agent-quickstart (Markdown: /ai/guide/guide/agent-workflows/agent-quickstart.md)
4. Native code validation: /ixml/ixml-guide/development-environment/coding-agents (Markdown: /ai/guide/ixml/ixml-guide/development-environment/coding-agents.md)

First success: The agent follows the project instructions and shows a request preview without writing anything.
Sample: Agent recipes: /guide/agent-workflows/agent-recipes
Troubleshooting: CLI coverage and escalation: /guide/agent-workflows/cli-coverage-and-escalation
Reference: /docs/ai, /ixml, /zymba, /api, /db

#### Use ZeyOS business data

Answer questions from your records, and run record operations you explicitly request, with or without an agent.

Prerequisites: The `zeyos` CLI, signed in with `zeyos login`.

Read in this order:
1. Agent quickstart: /guide/agent-workflows/agent-quickstart (Markdown: /ai/guide/guide/agent-workflows/agent-quickstart.md)
2. Agent recipes: /guide/agent-workflows/agent-recipes (Markdown: /ai/guide/guide/agent-workflows/agent-recipes.md)
3. Coding agents: /guide/agent-workflows/coding-agents (Markdown: /ai/guide/guide/agent-workflows/coding-agents.md)

First success: `zeyos count accounts --filter '{"type":1,"visibility":0}'` prints your number of customers.
Sample: Agent recipes: /guide/agent-workflows/agent-recipes
Troubleshooting: CLI coverage and escalation: /guide/agent-workflows/cli-coverage-and-escalation

## How to connect

- API base URL: `https://cloud.zeyos.com/{INSTANCE}/api/v1/`
- Auth: OAuth 2.0 bearer token from `https://cloud.zeyos.com/{INSTANCE}/oauth2/v1/`;
  send `Authorization: Bearer <token>` on every request.
- List/query a resource: HTTP `POST` to `/{resource}/` with a JSON body:
  `{ "fields": [...], "filters": {...}, "sort": [...], "limit": N, "offset": N, "expand": [...], "count": false }`
- Replace `{INSTANCE}` with the customer instance id (e.g. `demo`).
- Auth flow and scopes: /auth (OpenAPI: /__doc/openapi/oauth2.json).

### Zero-dependency example (curl)

List the 10 most recently modified active accounts:

```bash
curl -sS -X POST \
  -H "Authorization: Bearer $ZEYOS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"fields":["ID","lastname","customernum"],"filters":{"visibility":0},"sort":["-lastmodified"],"limit":10}' \
  "https://cloud.zeyos.com/$ZEYOS_INSTANCE/api/v1/accounts/"
```

## Recommended client: @zeyos/client

For most agent and scripting work, use the official ZeyOS client and CLI
instead of hand-rolling HTTP. They cover authentication, the query format,
and the generated API surface, and ship agent quickstart + recipe docs.

- Repository: https://github.com/zeyos/client
- Client, CLI and agent guides: /guide
- Agent setup (Kilo Code, Pi and OpenCode): /guide/agent-workflows/agent-setup
- Reusable project instructions: /ai/agent-instructions.md
- npm package: `@zeyos/client` (Node >= 18, ESM)

```js
import { createZeyosClient, MemoryTokenStore } from '@zeyos/client';

const client = createZeyosClient({
  platform: 'https://cloud.zeyos.com/demo/',
  validate: true,
  auth: {
    mode: 'oauth',
    oauth: { tokenStore: new MemoryTokenStore({ accessToken: process.env.ZEYOS_TOKEN }) },
  },
});

const tickets = await client.api.listTickets({
  fields: ['ID', 'name', 'status', 'priority'],
  filters: { visibility: 0 },
  limit: 10,
});
```

The repository also ships a `zeyos` CLI (use `--json` for agent-friendly
output) with a built-in auth flow. See /guide for the agent quickstart
and ready-made recipes (accounts, tickets, tasks, projects).

## Query model and gotchas

- List operations are `POST` requests with a JSON body, not `GET`.
- `fields`: array of column names, or an object to alias them. First-degree
  relations are addressable as `relation.field` (e.g. `assigneduser.name`).
- `filters`: composite JSON; operators `=, !=, <, <=, >, >=, IN, !IN`, plus
  regex/like operators for strings, combinable with `AND`/`OR`/`NOT` arrays.
- Use `visibility: 0` only on resources whose schema includes that field.
  For example, accounts has it; transactions does not. Inspect the schema first.
- Accounts use `lastname`/`firstname`, not `name`; account creation needs `currency`.
- Resolve every field and relationship before querying. CLI `describe` uses bundled
  metadata. With validation enabled, preflight follows every foreign-key hop and
  checks the terminal field (client/CLI 1.0.0+). Supply target-instance definitions through
  client `customFields` or CLI `ZEYOS_CUSTOM_FIELDS_FILE` to validate `extdata`
  references and writes. Missing custom-field metadata is a validation error.
  These checks require the client release containing complete join/custom-field
  validation; older releases do not provide them. They do not validate native SQL
  or compile iXML/Zymba scripts.
- Timestamps are Unix seconds (not milliseconds).
- Custom fields live in `extdata`; `expand` inlines JSON/binary columns.
- `filter` vs `filters`: the OpenAPI spec documents the body field as `filter`,
  while `@zeyos/client` and the CLI use `filters`. Follow the interface you use.
- Resolve human names to IDs before querying related records.
- Read first. Require explicit human confirmation before any write, delete, or
  outbound email. Never hardcode tokens — read them from the environment.

## Data model

ZeyOS exposes ~64 listable REST resources. The ones agents use most:
`accounts`, `contacts`, `addresses`, `opportunities`, `contracts`, `tickets`,
`tasks`, `projects`, `messages`, `notes`, `documents`, `transactions`,
`payments`, `items`, `prices`, `users`. Full schema and relationships:

- DB tables/views index: /ai/db/tables.json
- DB relations (foreign-key) graph: /ai/db/relations.json
- Full database reference (JSON): /__doc/dbref.json (alias /dbref.json)

## Machine-readable references

- REST OpenAPI: /__doc/openapi/api.json (alias /openapi.json)
- OAuth 2.0 OpenAPI: /__doc/openapi/oauth2.json (alias /openapi.oauth2.json)
- Simple Auth OpenAPI: /__doc/openapi/auth.json (alias /openapi.auth.json)
- Database reference: /__doc/dbref.json
- iXML reference (in-platform automation language): /__doc/ixmldoc.xml
- Zymba authoritative reference: /__doc/zymbaref.json (alias /zymbaref.json)
- OpenAPI tag/operation indexes: /ai/openapi/tags.json, /ai/openapi/operations.json
- iXML namespace index: /ai/ixml/namespaces.json
- Zymba indexes: /ai/zymba/namespaces.json, /ai/zymba/symbols.json
- Zymba entries preserve exact definitions, source JSON pointers and source hashes. Display signatures do not establish required parameters or runtime validity. Follow inheritance explicitly; guide drafts are not included.

Canonical sources (cloud.zeyos.com):
- https://cloud.zeyos.com/__doc/openapi/api.json
- https://cloud.zeyos.com/__doc/openapi/oauth2.json
- https://cloud.zeyos.com/__doc/openapi/auth.json
- https://cloud.zeyos.com/__doc/dbref.json
- https://cloud.zeyos.com/__doc/ixmldoc.xml
- https://cloud.zeyos.com/__doc/zymbaref.json

## Per-page Markdown

- Every guide, SDK and reference page has generated Markdown at `/ai/guide<route>.md`,
  for example /ai/guide/guide/agent-workflows/agent-setup.md for /guide/agent-workflows/agent-setup.
- /ai/guide/index.json — all exported pages with route, source revision, sha256 and bytes
- /ai/guide/index.md — the same list for reading
- Frontmatter carries title, description, canonical_url and source provenance. Links are absolute.
- /ai/ixml/commands.json — iXML commands with parents, children, result bindings and source lines

## Bulk ingestion (optional, for RAG)

In every scope, `llms.txt` is an index of links and `llms-full.txt` is the same
index followed by the complete text. Check `bytes` in /ai/manifest.json before loading a full set.

- /llms-full.txt — every working set below in one file
- /guide/llms-full.txt — domain working set (index: /guide/llms.txt)
- /api/llms-full.txt — domain working set (index: /api/llms.txt)
- /db/llms-full.txt — domain working set (index: /db/llms.txt)
- /ixml/llms-full.txt — domain working set (index: /ixml/llms.txt)
- /zymba/llms-full.txt — domain working set (index: /zymba/llms.txt)
- /ai/docs.jsonl, /ai/docs.jsonl.gz — chunked NDJSON (one record per chunk)
- /ai/download/zeyos-ai-docs.tar.gz — full deterministic offline bundle

## Human docs

- /api/openapi — REST API introduction and query format
- /docs/gettingstarted — REST API Browser + OAuth 2.0 primer
- /guide — JavaScript client, CLI, and agent workflows
- /api — interactive REST API reference
- /db — database documentation overview
- /ixml/ — iXML introduction
- /ixml/ixml-guide/development-environment/coding-agents — native XML formatting and validation workflow
- Native iXML/Zymba execution uses `zeysdk`; API validation does not compile scripts.
- `zeysdk run` executes remotely. Confirm the sandbox and authorization first.

## Discovery and caching

- /ai/manifest.json — stable artifact manifest (sha256 + bytes; offline-safe)
- /ai/index.json — same artifact list plus a build timestamp
- /ai/README.md — how the AI surface is organized
- Manifests list specs, entrypoints, indexes and bundles, not every leaf file.
- `documentationRevision` and `sources` in the manifest identify the fetched documentation; hashes identify content, not compatibility.
- Follow tag/table/namespace indexes for leaf URLs; /ai/docs.jsonl records include
  each chunk's URL, full UTF-8 text, sha256 and bytes.
- Cache listed artifacts by manifest hashes and individual chunks by JSONL hashes.

## Locale

- English at `/…`; German mirror under `/de/…` (e.g. /de/llms.txt).