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

# Workspace Members

> Create and manage workspace memberships, roles, project access, and activity.

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

<Warning>
  The former `/app/user` routes and member profile model change in 1.58. See [API migration 1.57 → 1.58](/en/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58#workspace-members) before upgrading your integration.
</Warning>

Use the Workspace Members API to manage an account's membership in a workspace. An account represents a person across Zylon, while a workspace member stores that account's workspace-specific state and roles.

Workspace member responses contain `id`, `org_id`, `account_id`, `state`, `roles`, and `created_at`. `id` is the workspace-member ID; `account_id` identifies the linked account and is available without `include`. Keep both values separate. If you previously saved a legacy user ID for creator comparisons or filters, follow [saved user-ID migration](/en/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58#migrate-saved-user-ids). Pass `include=Account` on supported endpoints to include the related account as `account`.

`GET /api/v1/account/{accountId}` includes the account's memberships in `workspace_members`. For account lists, request the same relationship with `GET /api/v1/account?include=WorkspaceMembers`. Nested `account` objects returned by the member endpoints omit it.

Valid workspace roles are `AppGuest`, `AppMember`, `AppAdmin`, and `AppOwner`.

<Note>Names and profile pictures belong to the account, not its workspace membership. Update those fields through `POST /api/v1/account/{accountId}`; use `me` as the account ID to update the authenticated account. `PUT /api/v1/app/member/{wsMemberId}` changes only the workspace role.</Note>

## Get the current workspace member

Use `GET /api/v1/app/me` to verify your token and workspace-member context.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Query | `include` | No | Comma-separated related data to include. Supported value: `Account`. |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/me?include=Account" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```json theme={null}
  {
    "id": "{wsMemberId}",
    "org_id": "{orgId}",
    "account_id": "{accountId}",
    "state": "Active",
    "roles": ["AppAdmin"],
    "created_at": "2026-02-08T14:12:45Z",
    "account": {
      "id": "{accountId}",
      "state": "Active",
      "email": "sasha@example.com",
      "name": "Sasha Patel",
      "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
      "provider": "Credentials",
      "roles": ["Workspace"],
      "created_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-02-08T14:12:45Z"
    }
  }
  ```
</Accordion>

## List workspace members

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Query | `state` | No | Comma-separated states: `Active` and `Inactive`. Both are included by default. |
  | Query | `include` | No | Comma-separated related data to include. Supported value: `Account`. |
  | Query | `page` | No | Absolute page number to fetch, 1-based. |
  | Query | `page_size` | No | Number of items per page. |
  | Query | `page_order` | No | `ASC` or `DESC`. |
  | Query | `after` | No | Cursor or value to paginate after. |
  | Query | `before` | No | Cursor or value to paginate before. |
  | Query | `first` | No | Limit to the first N items after a cursor. |
  | Query | `last` | No | Limit to the last N items before a cursor. |
  | Query | `total_count` | No | Include the total count in the response. |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/member?state=Active&include=Account&page=1&page_size=20&total_count=true" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```json theme={null}
  {
    "data": [
      {
        "id": "{wsMemberId}",
        "org_id": "{orgId}",
        "account_id": "{accountId}",
        "state": "Active",
        "roles": ["AppAdmin"],
        "created_at": "2026-02-08T14:12:45Z",
        "account": {
          "id": "{accountId}",
          "state": "Active",
          "email": "sasha@example.com",
          "name": "Sasha Patel",
          "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
          "provider": "Credentials",
          "roles": ["Workspace"],
          "created_at": "2026-01-10T09:00:00Z",
          "updated_at": "2026-02-08T14:12:45Z"
        }
      }
    ],
    "has_next_page": false,
    "has_previous_page": false,
    "total_count": 1
  }
  ```
</Accordion>

## Create a workspace member

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Body | `account_id` | Yes | ID of the account to add to the workspace. |
  | Body | `role` | Yes | Workspace role to assign. |
</Accordion>

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/member" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "{accountId}",
    "role": "AppMember"
  }'
```

<Accordion title="Example response">
  ```json theme={null}
  {
    "id": "{wsMemberId}",
    "org_id": "{orgId}",
    "account_id": "{accountId}",
    "state": "Active",
    "roles": ["AppMember"],
    "created_at": "2026-02-08T14:12:45Z"
  }
  ```
</Accordion>

## Get or update a workspace member

`GET /member/{wsMemberId}` accepts `me` in place of the workspace-member ID. `PUT /member/{wsMemberId}` requires an explicit workspace-member ID.

<Tabs>
  <Tab title="Get workspace member">
    <Accordion title="Endpoint parameters">
      | Type | Name | Required | Notes |
      | - | - | - | - |
      | Path | `wsMemberId` | Yes | Workspace-member ID, or `me` for the authenticated member. |
      | Query | `include` | No | Comma-separated related data to include. Supported value: `Account`. |
    </Accordion>

    ```bash theme={null}
    curl "https://{BASE_URL}/api/v1/app/member/{wsMemberId}?include=Account" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}"
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "id": "{wsMemberId}",
        "org_id": "{orgId}",
        "account_id": "{accountId}",
        "state": "Active",
        "roles": ["AppMember"],
        "created_at": "2026-02-08T14:12:45Z",
        "account": {
          "id": "{accountId}",
          "state": "Active",
          "email": "sasha@example.com",
          "name": "Sasha Patel",
          "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
          "provider": "Credentials",
          "roles": ["Workspace"],
          "created_at": "2026-01-10T09:00:00Z",
          "updated_at": "2026-02-08T14:12:45Z"
        }
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Update workspace member">
    <Accordion title="Endpoint parameters">
      | Type | Name | Required | Notes |
      | - | - | - | - |
      | Path | `wsMemberId` | Yes | Workspace-member ID. |
      | Body | `role` | Yes | Workspace role to assign. |
    </Accordion>

    ```bash theme={null}
    curl -X PUT "https://{BASE_URL}/api/v1/app/member/{wsMemberId}" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}" \
      -H "Content-Type: application/json" \
      -d '{
        "role": "AppAdmin"
      }'
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "id": "{wsMemberId}",
        "org_id": "{orgId}",
        "account_id": "{accountId}",
        "state": "Active",
        "roles": ["AppAdmin"],
        "created_at": "2026-02-08T14:12:45Z"
      }
      ```
    </Accordion>
  </Tab>
</Tabs>

## Activate or deactivate a workspace member

Both endpoints require an explicit workspace-member ID and return the updated workspace member.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Path | `wsMemberId` | Yes | Workspace-member ID. The value `me` is not supported. |
</Accordion>

<Tabs>
  <Tab title="Deactivate">
    ```bash theme={null}
    curl -X POST "https://{BASE_URL}/api/v1/app/member/{wsMemberId}/deactivate" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}"
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "id": "{wsMemberId}",
        "org_id": "{orgId}",
        "account_id": "{accountId}",
        "state": "Inactive",
        "roles": ["AppMember"],
        "created_at": "2026-02-08T14:12:45Z"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Activate">
    ```bash theme={null}
    curl -X POST "https://{BASE_URL}/api/v1/app/member/{wsMemberId}/activate" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}"
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "id": "{wsMemberId}",
        "org_id": "{orgId}",
        "account_id": "{accountId}",
        "state": "Active",
        "roles": ["AppMember"],
        "created_at": "2026-02-08T14:12:45Z"
      }
      ```
    </Accordion>
  </Tab>
</Tabs>

## List projects for a workspace member

Use `me` in place of `wsMemberId` to list projects for the authenticated workspace member.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Path | `wsMemberId` | Yes | Workspace-member ID, or `me` for the authenticated member. |
  | Query | `include` | No | Comma-separated related data to include. Supported value: `Members`. |
  | Query | `order_by` | No | Supported value: `Alphabetical`. |
  | Query | `order` | No | `ASC` or `DESC`. |
  | Query | `page` | No | Absolute page number to fetch, 1-based. |
  | Query | `page_size` | No | Number of items per page. |
  | Query | `page_order` | No | `ASC` or `DESC`. |
  | Query | `after` | No | Cursor or value to paginate after. |
  | Query | `before` | No | Cursor or value to paginate before. |
  | Query | `first` | No | Limit to the first N items after a cursor. |
  | Query | `last` | No | Limit to the last N items before a cursor. |
  | Query | `total_count` | No | Include the total count in the response. |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/member/{wsMemberId}/project?order_by=Alphabetical&order=ASC&page=1&page_size=20&total_count=true" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```json theme={null}
  {
    "data": [
      {
        "id": "{projectId}",
        "name": "Customer Insights",
        "goal": "Summarize weekly support trends.",
        "visibility": "Private",
        "member_count": 4,
        "default_member_role": "Editor",
        "default_role_enabled": true,
        "project_context": "Support analytics for Q1.",
        "use_citations": true,
        "use_system_prompt": true,
        "is_pinned": true
      }
    ],
    "has_next_page": false,
    "has_previous_page": false,
    "total_count": 1
  }
  ```
</Accordion>

## Latest artifacts for a workspace member

Use `me` in place of `wsMemberId` to get artifacts for the authenticated workspace member.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Path | `wsMemberId` | Yes | Workspace-member ID, or `me` for the authenticated member. |
  | Query | `latest` | No | Maximum number of latest artifacts to return. Defaults to `3`. |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/member/{wsMemberId}/latest-artifacts?latest=5" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

The response is an array of artifact objects. See [Artifacts](/en/v1.58/developer-manual/build-with-zylon/workspace-api/content/artifacts) for the response fields.

## Errors and edge cases

* **400**: invalid state, include value, role, or request body.
* **400**: a workspace member cannot activate or deactivate their own membership.
* **403**: insufficient permission to change workspace membership or roles.
* **404**: workspace member or related account not found.


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