Zum Hauptinhalt springen

ZeyOS for Agents and Applications

ZeyOS is a business platform that unifies CRM, project management, ticketing, invoicing, and related operational data behind a single API surface. For external integrations, you should think of ZeyOS as the central provider for business data and business logic that feeds coding agents, connected applications, internal tools, and automation services.

These docs are organized around two entry paths:

Scope

This documentation set currently focuses on external integrations. It covers the CLI, the JavaScript client, raw REST/OpenAPI usage, and reusable sample application patterns. It does not document authoring native ZeyOS platform artifacts.

How Are You Integrating?​

InterfaceBest forStart here
CLI (zeyos)Coding agents, shell automation, operational CRUD on curated resourcesCoding Agents
JavaScript Client (@zeyos/client)Browser apps, Node services, scheduled jobs, full generated API coverageApplication Developers
REST/OpenAPINon-JavaScript runtimes, SDK generation, custom HTTP clientsAPI Reference

Coverage Boundary​

  • The CLI is the default interface for coding agents, but it intentionally exposes a curated registry of common resources. Use zeyos resources to see the supported set.
  • The JavaScript client covers the broader generated API surface and is the recommended escalation path when the CLI registry is not enough.
  • The raw API reference remains the lowest-level source of truth for endpoints, query language, and schema details.

API Base URL​

Every ZeyOS instance exposes its REST API at a predictable base URL:

Text
https://cloud.zeyos.com/{INSTANCE}/api/v1/

Replace {INSTANCE} with your ZeyOS instance identifier (e.g. demo, acme-corp).

Authentication​

All API requests require authentication. ZeyOS supports two authentication methods:

  • OAuth 2.0 Bearer Tokens -- The recommended approach for server-side integrations, scheduled jobs, CLI tools, and browser apps that receive tokens from a trusted flow. Obtain tokens through the ZeyOS OAuth2 endpoint at https://cloud.zeyos.com/{INSTANCE}/oauth2/v1/.
  • Session Cookies -- For browser-based applications where the user is already logged into ZeyOS. The browser sends the ZEYOSID session cookie automatically.

Include a bearer token in the Authorization header for all API requests:

Text
Authorization: Bearer YOUR_ACCESS_TOKEN

See the Authentication guide for full details on the OAuth 2.0 Authorization Code flow, token refresh, token revocation, and session-based authentication.

Return Values and Error Handling​

The ZeyOS REST API returns JSON data along with an HTTP status code indicating the outcome of a request.

  • HTTP 200 or 201 indicates a successful response. The result is a JSON object.
  • HTTP 400 or greater indicates an error. The response is a text message describing the problem.

We recommend treating any HTTP status code greater than or equal to 400 as an error.

HTTP Methods​

The API uses the following HTTP methods, which differ from typical REST conventions in some cases:

OperationHTTP MethodDescription
ListPOSTRetrieve a filtered list of records (query parameters are sent in the request body)
GetGETRetrieve a single record by ID
CreatePUTCreate a new record
UpdatePATCHPartially update an existing record
DeleteDELETEDelete a record by ID
ExistsHEADCheck if a record exists (returns no body)
info

List operations use POST rather than GET because the query language (filters, field selection, sorting) can produce payloads that exceed URL length limits. Sending the query in the request body ensures complex queries work reliably.

Integration Conventions​

Across the CLI, JavaScript client, and sample applications, the same operational rules apply:

  • Prefer filters in JavaScript client code for compatibility across scalar and foreign-key fields.
  • Include visibility: 0 unless you intentionally want archived or deleted records.
  • For updates, pass changed fields alongside the ID directly ({ ID, status }) or wrap them in an explicit body object ({ ID, body: { status } }) — both work; the explicit body is only needed to disambiguate a payload field that collides with a reserved control key.
  • Treat extdata and expand as separate features:
    • extdata includes custom fields
    • expand inlines JSON or binary columns
  • Treat count-enabled list responses defensively. Different endpoints or client layers may return either a count wrapper or a list wrapper with count metadata.

Data Retrieval​

The API provides a flexible query language for retrieving data from any resource endpoint. List requests accept a JSON body with the following capabilities:

  • Field selection -- Request only the columns you need, including fields from related records via dot notation (e.g. contact.city, assigneduser.name).
  • Filters -- Restrict results using equality checks, comparison operators (<, >, IN, etc.), string matching (~, ~~, etc.), and composite logic (AND, OR, NOT).
  • Full-text search -- Search across a resource's indexed text fields with the query parameter.
  • Sorting -- Order results by one or more fields, ascending (+) or descending (-).
  • Pagination -- Control result size with limit and offset. Use count: true to retrieve the total number of matching records.
  • Extended data -- Include custom/extended data fields by passing extdata: 1 as a request parameter.
  • Expand -- Use the expand parameter to include JSON or binary column data that is omitted from list responses by default (e.g. binfile on messages, items on transactions).

See the Data Retrieval guide for the complete query language reference with examples.

Developer Tools​

This project includes tools to help you work with the ZeyOS REST API:

ToolDescriptionDocs
JavaScript Client (@zeyos/client)A dependency-light, auto-generated client library with generated methods for every API operation, OAuth 2.0 helpers, and automatic token refresh. Works in browsers and Node.js 18+.Getting Started
CLIA command-line interface for scripting and automation against your ZeyOS instance. Supports filtering, sorting, pagination, and multiple output formats.Getting Started
Agent WorkflowsCLI-first guidance for coding agents, JSON-first recipes, and escalation rules when the CLI registry is not enough.Coding Agents
Application DevelopersArchitecture, browser UI patterns, and server-side integration guidance for connected applications.Application Developers
Practical GuideA field-tested collection of implementation patterns, gotchas, and best practices learned from building real applications against the ZeyOS API.Practical Guide
Schema ReferenceField names, types, enum values, and GIN-indexed fields for the 20 most commonly used ZeyOS resources.Schema Reference

Sample Applications​

Three ready-to-run sample applications demonstrate different integration patterns:

SampleWhat it demonstratesDocs
Kanban BoardDrag-and-drop ticket management, optimistic UI updates, status changes via PATCH, task tables, project/account filteringKanban
CRM Account ListDot-notation joins, field aliasing, full-text search, sortable columns, pagination, modal editingCRM
DashboardKPI cards with count: true, parallel API queries, status distribution charts, overdue calculations, read-only patternsDashboard

Prerequisites​

  • A ZeyOS instance -- You need access to a ZeyOS cloud instance. Your instance URL follows the pattern https://cloud.zeyos.com/{INSTANCE}/.
  • Node.js 18+ -- Required for the JavaScript client.
  • Node.js 18.3+ -- Required for the CLI package.

Quick Example​

List the 10 most recently modified open tickets using curl:

Bash
curl -X POST "https://cloud.zeyos.com/demo/api/v1/tickets" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": ["ID", "name", "status", "priority", "duedate"],
    "filter": {"visibility": 0},
    "sort": ["-lastmodified"],
    "limit": 10
  }'

The same request using the JavaScript client:

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

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

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

console.log(tickets);

For long-lived OAuth sessions in trusted code, add clientId, clientSecret, and a refresh-capable token store. For browser-only apps, prefer session mode or a backend token broker instead of shipping client credentials.

tip

You can also use session authentication when running inside a browser where the user is already logged into ZeyOS. Set auth.mode to 'session' and the client will use browser cookies automatically. See the Authentication guide for details.

Next Steps​