Skip to content
Cyoda Documentation
Settings

cyoda help topic tree

The cyoda binary is self-documenting. Every flag, environment variable, endpoint, error code, metric, header, and operation is described by a help topic that ships with the binary. Topics are structured; many subdivide into drilldowns. The tree is stable across patch releases and evolves with minor releases.

For each topic listed below, the rendered mirror under /help/ carries the same content the binary’s cyoda help prints (pinned to v0.8.3). The binary you run is the authority for the version you run.

How to use it

Section titled “How to use it”
Terminal window
cyoda help                          # browse the whole tree
cyoda help <topic>                  # read one topic (e.g. `cyoda help search`)
cyoda help <topic> <subtopic>       # drill down (e.g. `cyoda help search async`)
cyoda help <topic> --format=json    # machine-readable
cyoda help <topic> --format=markdown # default off-TTY — paste into docs, PRs, chat

The tree

Section titled “The tree”
cyoda help admin

Both endpoint families require `ROLE_ADMIN` on the JWT and update process-local state atomically. State is **not** propagated across nodes; multi-node deployments must hit each node's endpoint separately.

cyoda help analytics

Cyoda Cloud exposes entity data as Trino SQL tables through a Trino connector. The connector uses the Schema Management REST API to discover table definitions and the WebSocket (STOMP) messaging API to stream entity rows at query time.

cyoda help audit

The audit API exposes a per-entity event log covering entity lifecycle changes (`EntityChange` events) and workflow state-machine progression (`StateMachine` events). Events are returned newest-first and support cursor-based pagination.

cyoda help auth

auth — authenticate client applications against cyoda.

  • cyoda help auth clients — auth.clients — provision and manage machine-to-machine (M2M) clients that authenticate against cyoda via the `client_credentials` grant.
  • cyoda help auth oidc — auth.oidc — register an external OIDC identity provider so JWTs it issues are accepted by cyoda directly, without re-minting at `/oauth/token`.
  • cyoda help auth tokens — auth.tokens — exchange credentials for a JWT at `POST /api/oauth/token`. Covers every supported grant and the canonical JWT claim contract that all cyoda tokens (M2M, OBO, federated OIDC, trusted-key) conform to.
  • cyoda help auth trusted-keys — auth.trusted-keys — register a public key with cyoda so JWTs you sign offline with the matching private key are accepted, without an IdP or `/oauth/token` round-trip.
cyoda help cli

cyoda is a Go binary that embeds the full platform: API server, schema engine, workflow runner, and storage plugins. Invoked with no subcommand, it starts the server using environment-provided configuration. Subcommands provide operational affordances — `init` for first-run bootstrap, `health` for liveness probes, `migrate` for schema migrations.

  • cyoda help cli health — `cyoda health` sends an HTTP GET to `http://127.0.0.1:<port>/readyz` and exits 0 if the server responds with HTTP 200. Any non-200 response or connection error causes exit 1.
  • cyoda help cli help — `cyoda help` is the built-in documentation browser. Topics are organized in a dot-separated tree (`cli`, `cli.serve`, `config.database`, etc.). Invoking `cyoda help` with no arguments prints a summary of all top-level topics. Invoking it with one or more topic segments navigates the tree.
  • cyoda help cli init — `cyoda init` is the recommended first step for local desktop use. It writes a minimal user config file that sets `CYODA_STORAGE_BACKEND=sqlite`, enabling persistent local storage without requiring a database server.
  • cyoda help cli migrate — `cyoda migrate` is a short-lived process that applies pending schema migrations for the configured storage backend, then exits cleanly — no admin listener, no background loops, no lingering goroutines.
  • cyoda help cli serve — Starting with no subcommand loads configuration from environment variables, validates the IAM mode, and binds the REST, gRPC, and admin listeners. The server is single-process, multi-tenant, and stateful — storage is provided by one of the pluggable backends (`memory`, `sqlite`, or `postgres`); see `cyoda help config` for backend selection.
cyoda help cloudevents

cyoda-go uses [CloudEvents v1.0](https://cloudevents.io) as the transport envelope for event-driven processing. Every payload carried inside a CloudEvent — workflow calculation requests, calculation responses, entity transaction events, snapshot state, model descriptors — is validated against a JSON Schema (Draft 2020-12).

cyoda help cluster

Multi-node cyoda is supported only on the `postgres` storage backend. All nodes are stateless and identical: no leader election, no shard ownership, no external service-discovery infrastructure. PostgreSQL is the single coordination layer. Snapshot Isolation with first-committer-wins (`REPEATABLE READ` + commit-time validation) provides correctness; gossip provides peer awareness; HMAC-signed routing tokens bind in-flight `pgx.Tx` handles to their owning node.

cyoda help config

Environment variables beat default values. The `_FILE` suffix variant takes precedence over the plain variable when both are set — for example, `CYODA_POSTGRES_URL_FILE=/etc/secrets/db-url` wins over `CYODA_POSTGRES_URL`. There are no command-line flags for configuration values; env vars are the sole configuration surface.

  • cyoda help config auth — config.auth — IAM mode, JWT issuer, HMAC secret, and admin bootstrap controls.
  • cyoda help config cluster — - `CYODA_CLUSTER_ENABLED` (bool, default: `false`) — enable multi-node clustering. - `CYODA_NODE_ID` (string, default: unset) — unique node identifier; required when `CYODA_CLUSTER_ENABLED=true`; any non-empty string is accepted. - `CYODA_NODE_ADDR` (string, default: `http://localhost:8080`) — this node's HTTP base URL; must include scheme (`http://` or `https://`). - `CYODA_GRPC_NODE_ADDR` (string, default: unset) — this node's gRPC endpoint advertised to peers (`host:port`, no scheme). When set, peers dial this address for cross-node gRPC callback forwarding. When unset, peers derive the gRPC address from this node's HTTP host plus their own `CYODA_GRPC_PORT` (uniform-deployment default). - `CYODA_GOSSIP_ADDR` (string, default: `:7946`) — gossip protocol listen address; format `[host]:port` — parsed via `net.SplitHostPort`; invalid format causes startup failure. - `CYODA_GOSSIP_STABILITY_WINDOW` (duration, default: `2s`) — gossip stability window. - `CYODA_SEED_NODES` (string, default: empty) — comma-separated list of seed node addresses (e.g., `node1.example.com:7946,node2.example.com:7946`); empty means single-node or seed-discovery handled externally. - `CYODA_HMAC_SECRET` (string, default: unset) — hex-encoded HMAC secret for inter-node dispatch authentication; required when `CYODA_CLUSTER_ENABLED=true`. Supports `_FILE` suffix. - `CYODA_PROXY_TIMEOUT` (duration, default: `30s`) — request proxy timeout. - `CYODA_DISPATCH_WAIT_TIMEOUT` (duration, default: `5s`) — how long the dispatcher polls gossip for a compute member with matching tags. - `CYODA_DISPATCH_FORWARD_TIMEOUT` (duration, default: `30s`) — HTTP timeout for the cross-node forwarding call. - `CYODA_TX_TOKEN_TTL` (duration, default: `90s`) — TTL of the signed transaction routing token minted on processor/criteria dispatch; must be ≥ `CYODA_DISPATCH_FORWARD_TIMEOUT` so the token remains valid through the full round-trip and callback verification, including the forwarded-chain case where two budgets stack. - `CYODA_KEEPALIVE_INTERVAL` (int, default: `10`) — keep-alive send interval in seconds. - `CYODA_KEEPALIVE_TIMEOUT` (int, default: `30`) — keep-alive timeout in seconds.
  • cyoda help config cors — config.cors — Cross-Origin Resource Sharing (CORS) controls for the public HTTP surface.
  • cyoda help config database — config.database — storage backend selection and per-backend connection settings.
  • cyoda help config grpc — config.grpc — gRPC listener settings and compute-node credentials.
  • cyoda help config scheduler — - `CYODA_SCHEDULER_ENABLED` (bool, default: `true`) — kill switch for the coordinator scan loop. - `CYODA_SCHEDULER_SCAN_INTERVAL` (duration, default: `1s`) — coordinator scan cadence. - `CYODA_SCHEDULER_BATCH_SIZE` (int, default: `100`) — max due tasks pulled per scan. - `CYODA_SCHEDULER_DISTRIBUTION` (string, default: `round-robin`) — dispatch-target selection strategy: `round-robin` or `self`. Forced to `self` whenever `CYODA_CLUSTER_ENABLED=false`. - `CYODA_SCHEDULER_COORDINATOR` (string, default: `lowest-node-id`) — coordinator-election strategy; the member with the lexicographically smallest node ID scans on each tick. - `CYODA_SCHEDULER_REDISPATCH_BACKOFF` (duration, default: `30s`) — best-effort re-dispatch throttle window applied to a task once it is picked up, so the same due task isn't immediately re-dispatched on the next scan. - `CYODA_SCHEDULER_EXPIRY_GRACE` (duration, default: `100ms`) — grace band above a scheduled transition's `timeoutMs` before it is expired instead of fired late; size to at least the maximum expected inter-node clock skew.
  • cyoda help config schema — config.schema — schema-extension log tuning.
cyoda help crud

Entities are instances of models. Each entity has a UUID, a model reference (`entityName`, `modelVersion`), and a lifecycle state managed by the workflow engine. Creating an entity requires the referenced model to be in `LOCKED` state. All write operations run within a Cyoda transaction and return a `transactionId` alongside the affected entity IDs.

cyoda help errors

Every error response from the Cyoda REST API carries a structured `errorCode` in the `properties` object. Multiple codes may share the same HTTP status. Programmatic handling keys on `errorCode`, not HTTP status.

  • cyoda help errors BAD_REQUEST — Fired when the server cannot parse or structurally process the incoming request. Common triggers include invalid JSON, missing required fields, unsupported format specifiers, or mutually exclusive parameters being set simultaneously.
  • cyoda help errors CLUSTER_NODE_NOT_REGISTERED — The request was routed to or requires a specific cluster node that is not present in the registry. Occurs during startup, rolling restarts, or after a node failure before the gossip layer has converged.
  • cyoda help errors COMPOSITE_KEY_UNSUPPORTED — Composite unique key enforcement is an optional capability that storage backends may or may not implement. This error is returned when a model defines one or more unique keys but the backend does not implement the `CompositeUniqueKeyCapable` interface.
  • cyoda help errors COMPUTE_MEMBER_DISCONNECTED — The compute member responsible for executing a processor or workflow step disconnected before completing the operation. The task may or may not have been executed.
  • cyoda help errors CONDITION_TYPE_MISMATCH — Validation is parse-based: a comparison or range operand is rejected only when it parses into none of the field's declared DataTypes. For example `"abc"` against a DOUBLE field is rejected — it is not a number. A numeric-looking string against a polymorphic `[INTEGER, STRING]` field is accepted (it parses as STRING).
  • cyoda help errors CONFLICT — The server detected that the entity was modified by another writer between the time it was read and the time the current write was committed. Normal outcome under concurrent load.
  • cyoda help errors DISPATCH_FORWARD_FAILED — The cluster dispatcher attempted to forward a processor invocation or criteria evaluation to a peer node but the HTTP call to that peer failed (network error, peer crash, or connection refused). The operation has not been executed on the target node.
  • cyoda help errors DISPATCH_TIMEOUT — A workflow processor or criteria evaluation was dispatched to a compute member but the response did not arrive within the dispatch timeout window. The underlying task may or may not have completed on the remote node.
  • cyoda help errors ENTITY_MODIFIED — When an entity update request carries an `If-Match` header, the server requires the supplied transaction ID to equal the entity's current `meta.transactionId`. A mismatch means another writer has updated the entity since the caller's last read. The optimistic-concurrency guard rejects the update rather than silently overwrite.
  • cyoda help errors ENTITY_NOT_FOUND — No entity with the given ID exists in the tenant's data store, or the entity existed at a point-in-time that precedes the requested snapshot. Also returned for audit log lookups when the specified event or message cannot be found.
  • cyoda help errors EPOCH_MISMATCH — Shard ownership is tracked by an epoch counter that increments whenever the cluster re-partitions. A write is rejected with this error when the writing node's cached epoch is stale — another node has since taken ownership of the shard. This prevents split-brain writes.
  • cyoda help errors FEATURE_DISABLED — Returned by trusted-key endpoints when `CYODA_IAM_TRUSTED_KEY_REGISTRATION_ENABLED=false` (the default):
  • cyoda help errors FORBIDDEN — The request was authenticated successfully but the caller's JWT claims do not include the role required by the endpoint (for example, `admin` is required for administrative operations). Tenant mismatch — where the caller's tenant does not match the resource — also produces this error.
  • cyoda help errors HELP_TOPIC_NOT_FOUND — Returned by `GET {ContextPath}/help/{topic}` when `{topic}` is well-formed (matches `[A-Za-z0-9._-]+`) but does not resolve to any topic in the tree. Clients should `GET {ContextPath}/help` to discover available topic paths.
  • cyoda help errors IDEMPOTENCY_CONFLICT — The idempotency key is supplied via the `Idempotency-Key` HTTP header on collection create and update requests. See `crud` for the request shape.
  • cyoda help errors INCOMPATIBLE_TYPE — Returned by `POST /entity/{format}/{name}/{version}` and the entity-update surfaces when a leaf field's value cannot be coerced into the model's declared DataType (e.g. submitting `"abc"` against an `INTEGER` field, or `13.111` against an `INTEGER` field on a model whose `changeLevel` is empty so type widening is not in scope).
  • cyoda help errors INVALID_CHANGE_LEVEL — The `changeLevel` path segment must be exactly one of: `ARRAY_LENGTH`, `ARRAY_ELEMENTS`, `TYPE`, or `STRUCTURAL`. Comparison is case-sensitive. Any other value (including the empty string, lower-cased variants, or typos) yields this error.
  • cyoda help errors INVALID_CONDITION — Endpoints that accept a search-style condition in the request body — grouped statistics and the conditional form of delete-by-model — reject a body whose condition cannot be parsed or is otherwise structurally invalid. The condition type is unrecognised, a nested clause is malformed, the JSON does not match the expected condition envelope, an `operatorType` is not one of the canonical operators, a `MATCHES_PATTERN` regex is malformed, or a `BETWEEN`/`BETWEEN_INCLUSIVE` operator's value is not a two-element array.
  • cyoda help errors INVALID_FIELD_PATH — Before executing a search, the server validates that every data-field path referenced by the condition (e.g. `$.price`, `$.profile.email`) resolves against the target model's locked schema. Lifecycle paths (`state`, `previousTransition`, etc.) and meta paths (`$._meta.*`) bypass this check.
  • cyoda help errors INVALID_UNIQUE_KEY — A composite unique key requires every declared field to be present and non-null. This error is returned when the entity payload is missing a value for at least one key field, or the value cannot be normalized to a valid claim (for example, a NaN or ±Infinity for a numeric key field).
  • cyoda help errors INVALID_UNIQUE_KEY_DEFINITION — Each unique key on a model must have a non-empty list of field paths, a unique name within the model, and field paths that resolve to existing, non-ambiguous fields in the model schema. This error is returned when a submitted model definition violates one of these structural requirements.
  • cyoda help errors KEY_OWNED_BY_DIFFERENT_TENANT — Trusted keys are tenant-scoped. When `POST /oauth/keys/trusted` is called with a `keyId` that already belongs to a different tenant, the request is rejected with `409`. Pick a fresh `keyId` (the caller cannot see or affect the other tenant's keys).
  • cyoda help errors KEYPAIR_NOT_FOUND — Returned by:
  • cyoda help errors M2M_CLIENT_NOT_FOUND — Returned by `/clients` admin endpoints when the supplied `clientId` does not match any registered M2M client in the caller's tenant:
  • cyoda help errors MODEL_ALREADY_LOCKED — Returned by any admin operation that requires the model be in the `UNLOCKED` state, including:
  • cyoda help errors MODEL_ALREADY_UNLOCKED — Returned when `POST /model/{name}/{version}/unlock` is issued against a model whose current state is `UNLOCKED`. Distinct from `MODEL_NOT_LOCKED`, which is reserved for the entity-write-without-lock path on the entity service: this code is the symmetric counterpart of `MODEL_ALREADY_LOCKED` for the admin lifecycle.
  • cyoda help errors MODEL_HAS_ENTITIES — Both `POST /model/{name}/{version}/unlock` and `DELETE /model/{name}/{version}` require zero entities of the target model. The cardinality check guards against silent loss of data and against schema drift on a model whose lifecycle is presumed frozen.
  • cyoda help errors MODEL_NOT_FOUND — The entity type or model name specified in the request does not exist in the tenant's model registry. Occurs on write paths (creating entities with an unknown type, importing data that references a missing model, performing model lifecycle transitions on a model ID that does not exist) and on read paths (list, stats, grouped-stats, and search operations that reference an unregistered model).
  • cyoda help errors MODEL_NOT_LOCKED — Entity creation and bulk write operations require the model to be in the `LOCKED` lifecycle state. Models in `DRAFT` or unlocked-for-editing state reject writes to prevent schema changes from affecting in-flight data.
  • cyoda help errors NO_COMPUTE_MEMBER_FOR_TAG — Workflow processors are dispatched to nodes that advertise matching compute tags. When no node with the required tag is alive in the cluster within the configured wait timeout (`CYODA_DISPATCH_WAIT_TIMEOUT`), the operation is rejected with this error.
  • cyoda help errors NOT_FOUND — Returned by administrative endpoints (key pair lifecycle, trusted-key lifecycle) when the supplied identifier does not match any registered resource. The submitted identifier is never echoed in the response body — only a generic descriptor — so attackers cannot use the response as a reflection oracle. The identifier is logged server-side at INFO for operator correlation.
  • cyoda help errors NOT_IMPLEMENTED — The route is defined and accepted by the server but the handler returns this error because the feature is pending implementation. Distinct from a `404` — the endpoint exists without a functional implementation.
  • cyoda help errors OIDC_INVALID_TENANT — cyoda treats legal entity identifiers as UUIDs. OIDC provider ownership is recorded as a `uuid.UUID` `OwnerLegalEntityID` field, which keys both the per-tenant KV blob storage and the validated user-context tenant binding at token validation time.
  • cyoda help errors OIDC_PROVIDER_DUPLICATE — Each tenant may register a given `wellKnownConfigUri` only once. Submitting `POST /oauth/oidc/providers` with a URI that is already registered for the caller's tenant returns this error.
  • cyoda help errors OIDC_PROVIDER_INACTIVE — `PATCH /oauth/oidc/providers/{id}` requires the provider to be in the active state. If the provider has been invalidated via `POST /oauth/oidc/providers/{id}/invalidate`, this error is returned.
  • cyoda help errors OIDC_PROVIDER_NOT_FOUND — The provider UUID supplied in the path parameter does not correspond to a registered OIDC provider for the caller's tenant. Either the provider was never registered, was deleted, or the UUID belongs to a different tenant (cross-tenant existence is not disclosed).
  • cyoda help errors OIDC_SSRF_BLOCKED — When registering an OIDC provider, cyoda validates the `wellKnownConfigUri` against a blocklist of private address ranges (loopback, RFC1918, link-local, IPv6 ULA). If the URI's hostname resolves to any blocked range, the registration is rejected to prevent Server-Side Request Forgery attacks.
  • cyoda help errors POLYMORPHIC_SLOT — A model can define polymorphic slots — fields whose schema varies based on a discriminator value. This error fires when the payload's discriminator selects a variant whose schema the provided data fails to match, or when the discriminator value itself is unrecognised.
  • cyoda help errors PRECONDITION_REQUIRED — PATCH applies a merge patch to the entity's stored state rather than replacing it wholesale. Because the patch is applied relative to the current stored data, cyoda-go requires the caller to state a precondition explicitly via `If-Match`. Omitting the header entirely is rejected.
  • cyoda help errors SCAN_BUDGET_EXHAUSTED — Some conditions are not indexable — for example a regex or a wildcard path match — so the backend must scan candidate rows and post-filter them in the engine instead of pushing the predicate to storage. When the number of rows scanned this way exceeds the configured scan-budget limit, the request fails fast instead of running unbounded.
  • cyoda help errors SCHEDULE_FUNCTION_INVALID_RESULT — A `TransitionSchedule.function` callout must return `resultKind: "Schedule"` with a value shaped `{fireAt|fireAfterMs, expireAt?|expireAfterMs?}` — exactly one of `fireAt`/`fireAfterMs`, and at most one of `expireAt`/`expireAfterMs`. This error is raised when the compute node returns a different `resultKind`, or a `Schedule` value that is malformed: missing or duplicate fire/expiry fields, an unknown field, or a non-numeric value.
  • cyoda help errors SEARCH_JOB_ALREADY_TERMINAL — Search jobs are long-running asynchronous operations. Once a job reaches a terminal state it cannot be cancelled, resumed, or otherwise modified. This error is returned when such an operation is attempted on a finished job.
  • cyoda help errors SEARCH_JOB_NOT_FOUND — Polling a search job by ID returns this error when the job ID is unknown or belongs to a different tenant. Jobs are tenant-scoped; a valid job ID from one tenant is not visible to another.
  • cyoda help errors SEARCH_RESULT_LIMIT — Direct (synchronous) search is bounded-or-fail: `limit` caps the matched result set rather than paging it. When more entities match than the limit allows, the request is rejected — it never returns a truncated prefix, because a partial result would be indistinguishable from a complete one.
  • cyoda help errors SEARCH_SHARD_TIMEOUT — Distributed search fans out to multiple shards in parallel. If any shard does not return results before the search timeout expires, the job is marked failed and this error is returned. Occurs under high load, during partial cluster degradation, or with expensive queries.
  • cyoda help errors SERVER_ERROR — The server encountered an unclassified internal error. The response body contains a `ticket` UUID that correlates with the server-side error log. No internal details are exposed in the response.
  • cyoda help errors TRANSACTION_EXPIRED — Transaction tokens are short-lived bearer tokens issued when a transaction is opened. This error fires when the token's `exp` claim is in the past at the time the proxy validates it. The transaction itself may still be active server-side, but the token is no longer valid for routing.
  • cyoda help errors TRANSACTION_NODE_UNAVAILABLE — Transaction state is pinned to the node that opened it. If that node crashes or becomes unreachable while the transaction is in progress, subsequent requests using the transaction token are rejected with this error because the proxy cannot forward them to the owner.
  • cyoda help errors TRANSACTION_NOT_FOUND — The transaction ID supplied in the request does not correspond to an active transaction. The transaction may have been committed, rolled back, expired, or may never have existed. Also occurs when a request is mis-routed to a node that never opened the transaction.
  • cyoda help errors TRANSITION_NOT_FOUND — Entity workflow state machines define explicit transitions between states. This error fires when a transition is triggered that does not exist in the model's workflow definition for the entity's current state. Also occurs when the transition name is misspelled or when the entity is in a terminal state that allows no further transitions.
  • cyoda help errors TRUSTED_KEY_CAP_REACHED — `POST /oauth/keys/trusted` enforces a per-tenant cap (default 10, configurable via `CYODA_IAM_TRUSTED_KEY_MAX_PER_TENANT`). The cap counts only currently-valid keys (Active and not past `validTo`). Delete or invalidate older keys, or raise the cap.
  • cyoda help errors TRUSTED_KEY_NOT_FOUND — Returned by trusted-key admin endpoints when the supplied KID does not match any registered key:
  • cyoda help errors TX_CONFLICT — Reserved. Not currently emitted by any cyoda-go code path.
  • cyoda help errors TX_COORDINATOR_NOT_CONFIGURED — Reserved. Not currently emitted by any cyoda-go code path.
  • cyoda help errors TX_NO_STATE — Reserved. Not currently emitted by any cyoda-go code path.
  • cyoda help errors TX_REQUIRED — Reserved. Not currently emitted by any cyoda-go code path.
  • cyoda help errors UNAUTHORIZED — Returned when the `Authorization` header is missing, the bearer token is expired, the token signature is invalid, or the token was issued by an untrusted issuer. Also returned when a request reaches a protected route with no identity context established by the auth middleware.
  • cyoda help errors UNIQUE_VIOLATION — The entity payload contains field values that collide with an existing entity's composite unique key. Unlike an optimistic-concurrency CONFLICT (which is retryable), a unique-key violation is a permanent data constraint — retrying the same payload without changing the key field values will produce the same result.
  • cyoda help errors UNSUPPORTED_ALGORITHM — cyoda-go v0.8.0 signs and verifies only `RS256`. Other enum values declared in the OpenAPI spec (`RS384`, `RS512`, `PS256`, `PS384`, `PS512`, `ES256`, `ES384`, `ES512`, `EdDSA`) are rejected with this error. Cyoda Cloud supports the full enum; parity is tracked in a v0.8.1 follow-up.
  • cyoda help errors UNSUPPORTED_KEY_TYPE — `POST /oauth/keys/trusted` accepts only `kty: "RSA"` in v0.8.0. Cloud also supports `kty: "EC"` and `kty: "OKP"`; cyoda-go parity is tracked in a v0.8.1 follow-up.
  • cyoda help errors UNSUPPORTED_MEDIA_TYPE — Returned by PATCH in two situations:
  • cyoda help errors VALIDATION_FAILED — Unlike `BAD_REQUEST` (which covers parse failures), this error is returned when the payload is parseable but violates the registered model schema — for example, a required field is missing, a value is out of the allowed range, or a workflow guard condition is not satisfied. The error detail includes the specific validation failure.
  • cyoda help errors WORKFLOW_FAILED — During an entity create or transition operation the associated workflow processors (pre-processors, post-processors) or guard conditions ran but one of them signalled failure. The failure message from the processor is included in the error detail.
  • cyoda help errors WORKFLOW_NOT_FOUND — Entity models reference a workflow by name to govern state transitions. This error is returned when the named workflow cannot be found in the tenant's workflow registry, during entity type registration or when a model references a workflow that was deleted.
  • cyoda help errors WORKFLOW_SCHEMA_VERSION_UNSUPPORTED — Every workflow definition must declare a schema version in `MAJOR.MINOR` format (for example `"version": "1.1"`). This error is returned when the import request contains a version string that does not match any supported schema version.
cyoda help grpc

cyoda-go exposes one gRPC service: `CloudEventsService` (package `org.cyoda.cloud.api.grpc`). All gRPC methods use the CloudEvents Protobuf envelope (`io.cloudevents.v1.CloudEvent`) as both request and response types. The event type string in the CloudEvent envelope selects the operation; the JSON payload in `text_data` (or `binary_data`) carries the operation-specific body.

cyoda help helm

The chart at `deploy/helm/cyoda` deploys cyoda-go on Kubernetes as a StatefulSet backed by an external PostgreSQL database. The chart requires Kubernetes `>=1.31.0`. Chart version: `0.1.0`. App version: `0.1.0` (synchronized to the binary by the `bump-chart-appversion.yml` CI workflow).

cyoda help messages

An edge message is an arbitrary JSON payload stored under a server-generated time-UUID together with a fixed set of AMQP-aligned headers and an optional flat metadata map. The store is standalone: a message is not an entity, and creating one does not touch the workflow engine — no transition fires, no processor or criterion runs. Edge messaging is a durable, tenant-scoped staging buffer at the platform edge, a peer of the entity store rather than part of it.

cyoda help models

A model is a named, versioned schema registered per tenant. Every entity in the system is an instance of exactly one model. Models are identified by `(entityName, modelVersion)`. The model ID is a deterministic UUID v5 derived from that key: `UUID.newSHA1(NameSpaceURL, "{entityName}.{modelVersion}")`.

cyoda help openapi

cyoda-go generates its OpenAPI 3.1 specification from the embedded `api/openapi.yaml` file compiled into the binary at build time. The spec is served at `/openapi.json` with runtime-patched server URLs. The Scalar API Reference UI is served at `/docs` and loads the spec from `/openapi.json`.

cyoda help predicates

predicates — operator catalog and evaluation semantics for the `Condition` DSL used by search (`cyoda help search`) and workflow/transition criteria (`cyoda help workflows`). Both consume the same kernel, so everything here applies identically to both.

cyoda help quickstart

cyoda-go is a single-process, multi-tenant REST and gRPC API server backed by a pluggable embedded database management system. Storage backends are `memory`, `sqlite`, and `postgres`; authentication modes are `mock` and `jwt`. All configuration is via environment variables with a `CYODA_` prefix.

cyoda help run

cyoda-go is a single-process, multi-tenant REST and gRPC API server. It starts in serving mode when invoked with no subcommand. All configuration is via environment variables with a `CYODA_` prefix. The binary, Docker image, and Helm chart run the same binary; only the environment configuration differs across run modes.

cyoda help search

Search operates against a specific entity model `(entityName, modelVersion)`. Two modes are supported:

cyoda help telemetry

cyoda-go integrates the OpenTelemetry Go SDK (`go.opentelemetry.io/otel`). The **metric scrape pipeline is always on**: at startup the binary creates a meter provider with an OpenTelemetry → Prometheus exporter and serves it at `:9091/metrics`, regardless of `CYODA_OTEL_ENABLED`. No collector is required to scrape metrics.

cyoda help workflows

A workflow definition is a named finite state machine attached to an entity model. Workflows are stored per model reference `(entityName, modelVersion)`. A model may have multiple workflow definitions; the engine selects the matching one per entity using the workflow-level `criterion` field evaluated at entity creation time. When no `criterion` matches, the engine uses the default built-in workflow.

  • cyoda help workflows schema-version — workflows schema-version — semver `MAJOR.MINOR` contract identifying the workflow-import DTO shape that a workflow definition was authored against.