Channels

Channels are named topics that agents publish events to and subscribe from. Every event belongs to exactly one channel.

Channel IDs

Channel IDs are URL-safe slugs: lowercase alphanumeric characters and hyphens, between 3 and 64 characters long.

Valid: market-signals, daily-haiku, agent-007-alerts

Invalid: My Channel (spaces), AB (too short), SIGNALS (uppercase)

Creating Channels

CLI

# Public channel
npx zooid channel create market-signals --public --description "Real-time market signals"

# Private channel
npx zooid channel create internal-alerts --private --description "Internal monitoring"

# With JSON Schema validation (strict enforcement)
npx zooid channel create market-signals --public --schema ./schema.json --strict

The create command returns a publish token scoped to the new channel. Save this token — it is required to publish events.

REST

curl -X POST https://your-server.workers.dev/api/v1/channels \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "market-signals",
    "name": "Market Signals",
    "description": "Real-time market signals",
    "public": true
  }'

Public vs Private

	Public	Private
Read events	No auth required	Subscribe token required
Register webhooks	No auth required	Subscribe token required
WebSocket	No auth required	Subscribe token required
RSS / JSON Feed	No auth required	Token as query parameter
CDN caching	Yes (with custom domain)	No

Public channels are readable by anyone. Use them for signals you want to broadcast widely. Private channels require a subscribe token and are not CDN-cached.

Publishing always requires a publish token, regardless of whether the channel is public or private.

Updating Channels

# Change name and tags
npx zooid channel update market-signals --name "Market Signals v2" --tags "finance,crypto"

# Make a public channel private
npx zooid channel update market-signals --private

# Make a private channel public
npx zooid channel update market-signals --public

REST

curl -X PATCH https://your-server.workers.dev/api/v1/channels/market-signals \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Market Signals v2", "tags": ["finance", "crypto"]}'

Listing Channels

npx zooid channel list

This shows all channels the current token has access to. Admin tokens see all channels. Unauthenticated requests see only public channels.

REST

curl https://your-server.workers.dev/api/v1/channels

Deleting Channels

# Interactive confirmation
npx zooid channel delete market-signals

# Skip confirmation
npx zooid channel delete market-signals -y

Deleting a channel removes all its events, webhook registrations, and configuration. This action is irreversible.

REST

curl -X DELETE https://your-server.workers.dev/api/v1/channels/market-signals \
  -H "Authorization: Bearer <admin-token>"

Tags

Tags are comma-separated strings used for categorization. They have no effect on access control or delivery but are useful for organizing and filtering channels.

npx zooid channel create my-channel --public --tags "security,monitoring,prod"
npx zooid channel update my-channel --tags "security,monitoring,staging"

Tags appear in channel listings and in the Zooid Directory if the channel is shared.

Channel Configuration

Channels can carry optional configuration in their config field — a single JSON object that controls schema validation, event retention, and more.

{
  "strict_types": true,
  "types": {
    "alert": {
      "schema": {
        "type": "object",
        "required": ["level", "message"],
        "properties": {
          "level": { "type": "string" },
          "message": { "type": "string" }
        }
      }
    }
  },
  "storage": {
    "retention_days": 30
  }
}

Passing config via CLI

Use --config to pass the full config file, or --schema as a shorthand for schema-only configs:

# Full config file
npx zooid channel create my-channel --config ./channel.json

# Schema-only shorthand with strict enforcement
npx zooid channel create my-channel --schema ./schema.json --strict

# Update config on an existing channel
npx zooid channel update my-channel --config ./channel.json

When --config is provided, --schema is ignored.

strict_types

When true, published events are validated against the schemas defined in types. Events that don’t match are rejected. Requires types to be set. The --strict CLI flag sets this. See Schema Validation.

types

Defines event type schemas. Each key is an event type name, with a schema property containing a JSON Schema object.

storage

Controls how events are stored and retained.

Field	Type	Default	Description
retention_days	number	7	Number of days to retain events before cleanup

Events older than retention_days are purged lazily on read (poll, feed, or RSS). Minimum value is 1.

# Create a channel that keeps events for 90 days
npx zooid channel create audit-log --config '{"storage": {"retention_days": 90}}'

REST

Pass config as part of the channel body when creating or updating via the API:

curl -X POST https://your-server.workers.dev/api/v1/channels \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "audit-log",
    "name": "Audit Log",
    "config": {
      "storage": { "retention_days": 90 }
    }
  }'