> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zylon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> API for automating and managing Zylon Workspace.

<Warning>
  **Upcoming release — Zylon 1.58**

  These 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](/en/v1.57/overview).
</Warning>

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](/en/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58) 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](/en/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58#migrate-saved-user-ids); retained legacy URLs do not perform this conversion.

## Base URL

All Workspace endpoints live under:

```
https://{BASE_URL}/api/v1
```

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

```bash theme={null}
-H "x-org: {org_slug}"
```

## 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](/en/v1.58/developer-manual/build-with-zylon/zylon-gpt-api/overview) 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](/en/v1.58/developer-manual/get-started/token-management) for all six scopes and creation rules.

## Core concepts

| Concept | Meaning |
| - | - |
| **Account** | The identity record that authenticates into Zylon. One account can belong to multiple organizations. |
| **Workspace member** | The organization-specific membership for an account. An account can have **multiple workspace members**, one per organization. |
| **Artifact** | A persisted piece of knowledge that can be retrieved in chats and tools. |

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:

<Accordion title="Pagination envelope example">
  ```json theme={null}
  {
    "data": [],
    "next_cursor": "cursor_next",
    "previous_cursor": "cursor_prev",
    "has_next_page": false,
    "has_previous_page": false,
    "total_count": 0
  }
  ```
</Accordion>

Use `page`, `page_size`, `after`, `before`, `first`, `last`, and `total_count` when they’re available on the endpoint.

## Workspace API sections

<CardGroup cols={3}>
  <Card title="General" icon="chart-line" href="/en/v1.58/developer-manual/build-with-zylon/workspace-api/general/overview">
    Analytics, issues, search, and system status endpoints.
  </Card>

  <Card title="Authentication" icon="key" href="/en/v1.58/developer-manual/build-with-zylon/workspace-api/authentication/openid">
    SSO login flows and workspace login/auth callbacks.
  </Card>

  <Card title="Workspace Members" icon="users" href="/en/v1.58/developer-manual/build-with-zylon/workspace-api/users/user">
    Create, update, and manage workspace-member access and organization membership.
  </Card>

  <Card title="Projects" icon="folder" href="/en/v1.58/developer-manual/build-with-zylon/workspace-api/projects/project">
    Provision projects, manage membership, and control visibility.
  </Card>

  <Card title="Chats" icon="message" href="/en/v1.58/developer-manual/build-with-zylon/workspace-api/chats/threads">
    Create threads, run interactions, and stream responses.
  </Card>

  <Card title="Content" icon="file" href="/en/v1.58/developer-manual/build-with-zylon/workspace-api/content/artifacts">
    Manage artifacts and integrations like Confluence, SharePoint, Filesystem, and Claromentis.
  </Card>
</CardGroup>

For manual log retrieval, use [Backoffice API: Logging](/en/v1.58/developer-manual/build-with-zylon/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.