# 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.

## 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","name","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/api
- Client, CLI and agent guides: /guide
- npm package: `@zeyos/client` (Node >= 18, ESM)

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

const client = createZeyosClient({
  platform: 'https://cloud.zeyos.com/demo/',
  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.
- Always pass `visibility: 0` unless you want archived/deleted records.
- 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
- OpenAPI tag/operation indexes: /ai/openapi/tags.json, /ai/openapi/operations.json
- iXML namespace index: /ai/ixml/namespaces.json

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

## Bulk ingestion (optional, for RAG)

- /llms-full.txt — one-shot, high-signal working set
- /api/llms-full.txt, /db/llms-full.txt, /ixml/llms-full.txt — per-domain sets
- /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

## 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
- Cache artifacts by `sha256` + `bytes` to skip unchanged content.

## Locale

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