Skip to main content
Upcoming release — Zylon 1.58These docs are published ahead of release so you can prepare your API integrations. The release image is not yet available. For installations running 1.57, use the 1.57 documentation.
The Workspace API lets you programmatically manage everything in Zylon Workspace—organizations, workspace members, projects, chats, artifacts, integrations, and reporting. Use it to automate admin workflows or integrate Zylon into your internal systems.

​
Upgrading to 1.58

Follow the 1.57 → 1.58 migration guide for retained legacy routes, artifact bodies, and chat/thread changes. If your integration uses user or account IDs, migrate affected mappings and comparisons: creator IDs now identify accounts, while membership APIs still use workspace-member IDs. Successful requests do not guarantee that stored IDs still match. For integrations that need user identity or creator filtering, use the current API and follow the member-ID-to-account-ID lookup; retained legacy URLs do not perform this conversion.

​
Base URL

All Workspace endpoints live under:

​
Organization header (x-org)

Workspace endpoints under /api/v1/app/* require the x-org header so Zylon knows which workspace organization to target. You can set x-org to either:
  • the organization slug (recommended), for example default
  • the organization ID (UUID)
Use this in requests:

​
Read-only token scopes

Workspace.Read.All permits Workspace reads and search, including organizations, workspace members, projects, artifacts, threads, interactions, issues, feedback, and integrations. It does not permit Workspace mutations; create, update, delete, join, and other write operations return 403. Read.All includes the same Workspace read/search permissions and also grants account/token/gateway inventory and Backoffice/meta reads. Its ZylonGPT read-only allowlist is usable only when the account token carries gateway_id; a Read.All token created without gateway context cannot call ZylonGPT. Effective access is always limited by the token owner’s role permissions. Multiple scopes combine their grants. See Token Management for all six scopes and creation rules.

​
Core concepts

This model supports multi‑org setups where the same person can be a member of multiple workspaces with different roles.

​
Pagination

Pagination is a shared model across the Workspace API. List endpoints return a page envelope with cursors:
Use page, page_size, after, before, first, last, and total_count when they’re available on the endpoint.

​
Workspace API sections

General

Analytics, issues, search, and system status endpoints.

Authentication

SSO login flows and workspace login/auth callbacks.

Workspace Members

Create, update, and manage workspace-member access and organization membership.

Projects

Provision projects, manage membership, and control visibility.

Chats

Create threads, run interactions, and stream responses.

Content

Manage artifacts and integrations like Confluence, SharePoint, Filesystem, and Claromentis.
For manual log retrieval, use Backoffice API: Logging.

​
Errors and edge cases

  • 401/403: token missing or insufficient permissions.
  • 404: resource IDs are invalid or deleted.
  • Redirect endpoints: login/callback routes return 302 responses intended for browsers.