Workspaces

GET /workspaces

List workspaces accessible to the authenticated user.

Authentication: JWT Bearer token

Request

No path, query, or body parameters.

Response

Response Example

json

{
  "data": [
    {
      "id": "ws-abcd-efgh",
      "name": "Product Development",
      "accountId": "acc-1234-5678",
      "isActive": true,
      "isDefault": true,
      "createdAt": "2026-01-20T09:00:00.000Z"
    },
    {
      "id": "ws-ijkl-mnop",
      "name": "Marketing",
      "accountId": "acc-1234-5678",
      "isActive": true,
      "isDefault": false,
      "createdAt": "2026-02-05T14:00:00.000Z"
    }
  ],
  "meta": {
    "total": 2
  },
  "error": null
}

Response Fields

Field	Type	Description
`id`	string	Workspace ID
`name`	string	Workspace display name
`accountId`	string	ID of the account this workspace belongs to
`isActive`	boolean	Whether the workspace is currently active
`isDefault`	boolean	Whether this is the user's default workspace
`createdAt`	string	ISO 8601 timestamp of workspace creation

Code Examples

cURLJavaScriptPython

bash

curl "https://api.chainabit.com/api/v1/workspaces" \
  -H "Authorization: Bearer $TOKEN"

javascript

const response = await fetch(
  `${BASE_URL}/workspaces`,
  {
    headers: {
      Authorization: `Bearer ${TOKEN}`,
    },
  }
);
const data = await response.json();

python

import requests

response = requests.get(
    f"{BASE_URL}/workspaces",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = response.json()

POST /workspaces

Create a new workspace in the authenticated account.

Authentication: JWT Bearer token

Request

Field	Type	Required	Constraints	Description
`slug`	string	Yes	URL-safe identifier	Workspace slug
`name`	string	Yes	Non-empty string	Display name for the workspace
`description`	string	No	Max 1024 chars	Optional description
`settings`	object	No	JSON object	Optional workspace settings

Response

Response Example

json

{
  "data": {
    "id": "ws-qrst-uvwx",
    "name": "Engineering",
    "accountId": "acc-1234-5678",
    "isActive": true,
    "isDefault": false,
    "createdAt": "2026-03-17T11:00:00.000Z"
  },
  "meta": null,
  "error": null
}

Response Fields

Field	Type	Description
`id`	string	Newly created workspace ID
`name`	string	Workspace display name
`accountId`	string	ID of the account this workspace belongs to
`isActive`	boolean	Always `true` on creation
`isDefault`	boolean	Whether this is the default workspace
`createdAt`	string	ISO 8601 timestamp of workspace creation

Code Examples

cURLJavaScriptPython

bash

curl -X POST "https://api.chainabit.com/api/v1/workspaces" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "engineering",
    "name": "Engineering"
  }'

javascript

const response = await fetch(`${BASE_URL}/workspaces`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    slug: "engineering",
    name: "Engineering"
  }),
});
const data = await response.json();

python

import requests

response = requests.post(
    f"{BASE_URL}/workspaces",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={"slug": "engineering", "name": "Engineering"},
)
data = response.json()

GET /workspaces/:id

Get a workspace by ID. The authenticated user must be a member of the workspace.

Authentication: JWT Bearer token (must be a workspace member)

Request

Replace $WORKSPACE_ID below with the id from a List Workspaces or Create Workspace response.

Response

Response Example

json

{
  "data": {
    "id": "ws-abcd-efgh",
    "name": "Product Development",
    "accountId": "acc-1234-5678",
    "isActive": true,
    "isDefault": true,
    "membersCount": 4,
    "createdAt": "2026-01-20T09:00:00.000Z"
  },
  "meta": null,
  "error": null
}

Response Fields

Field	Type	Description
`id`	string	Workspace ID
`name`	string	Workspace display name
`accountId`	string	ID of the account this workspace belongs to
`isActive`	boolean	Whether the workspace is currently active
`isDefault`	boolean	Whether this is the default workspace
`membersCount`	number	Total number of members in this workspace
`createdAt`	string	ISO 8601 timestamp of workspace creation

Code Examples

cURLJavaScriptPython

bash

curl "https://api.chainabit.com/api/v1/workspaces/$WORKSPACE_ID" \
  -H "Authorization: Bearer $TOKEN"

javascript

const WORKSPACE_ID = process.env.WORKSPACE_ID; // id from a list or create workspace response

const response = await fetch(`${BASE_URL}/workspaces/${WORKSPACE_ID}`, {
  headers: {
    Authorization: `Bearer ${TOKEN}`,
  },
});
const data = await response.json();

python

import os
import requests

workspace_id = os.environ["WORKSPACE_ID"]  # id from a list or create workspace response

response = requests.get(
    f"{BASE_URL}/workspaces/{workspace_id}",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = response.json()

PATCH /workspaces/:id

Update a workspace's name or settings. Requires owner or admin role.

Authentication: JWT Bearer token + Owner/Admin role required

Request

Replace $WORKSPACE_ID below with the id from a List Workspaces or Create Workspace response.

Field	Type	Required	Constraints	Description
`name`	string	No	Non-empty string	New display name for the workspace

Response

Response Example

json

{
  "data": {
    "id": "ws-abcd-efgh",
    "name": "Product & Design",
    "updatedAt": "2026-03-17T11:00:00.000Z"
  },
  "meta": null,
  "error": null
}

Response Fields

Field	Type	Description
`id`	string	Workspace ID
`name`	string	Updated workspace display name
`updatedAt`	string	ISO 8601 timestamp of this update

Code Examples

cURLJavaScriptPython

bash

curl -X PATCH "https://api.chainabit.com/api/v1/workspaces/$WORKSPACE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product & Design"
  }'

javascript

const WORKSPACE_ID = process.env.WORKSPACE_ID; // id from a list or create workspace response

const response = await fetch(`${BASE_URL}/workspaces/${WORKSPACE_ID}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Product & Design" }),
});
const data = await response.json();

python

import os
import requests

workspace_id = os.environ["WORKSPACE_ID"]  # id from a list or create workspace response

response = requests.patch(
    f"{BASE_URL}/workspaces/{workspace_id}",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={"name": "Product & Design"},
)
data = response.json()

PATCH /workspaces/:id/activation

Activate or deactivate a workspace. Requires owner or admin role.

Authentication: JWT Bearer token + Owner/Admin role required

Request

Replace $WORKSPACE_ID below with the id from a List Workspaces or Create Workspace response.

Field	Type	Required	Constraints	Description
`isActive`	boolean	Yes	`true` or `false`	Whether the workspace should be active

Response

Response Example

json

{
  "data": {
    "id": "ws-abcd-efgh",
    "isActive": false,
    "updatedAt": "2026-03-17T12:00:00.000Z"
  },
  "meta": null,
  "error": null
}

Response Fields

Field	Type	Description
`id`	string	Workspace ID
`isActive`	boolean	Updated activation status
`updatedAt`	string	ISO 8601 timestamp of this update

Code Examples

cURLJavaScriptPython

bash

curl -X PATCH "https://api.chainabit.com/api/v1/workspaces/$WORKSPACE_ID/activation" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false
  }'

javascript

const WORKSPACE_ID = process.env.WORKSPACE_ID; // id from a list or create workspace response

const response = await fetch(
  `${BASE_URL}/workspaces/${WORKSPACE_ID}/activation`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ isActive: false }),
  }
);
const data = await response.json();

python

import os
import requests

workspace_id = os.environ["WORKSPACE_ID"]  # id from a list or create workspace response

response = requests.patch(
    f"{BASE_URL}/workspaces/{workspace_id}/activation",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={"isActive": False},
)
data = response.json()

PUT /workspaces/:id/default

Set a workspace as the default workspace. Requires owner or admin role.

Authentication: JWT Bearer token + Owner/Admin role required

Request

Replace $WORKSPACE_ID below with the id from a List Workspaces or Create Workspace response.

Response

Response Example

json

{
  "data": {
    "id": "ws-abcd-efgh",
    "name": "Product Development",
    "isDefault": true,
    "updatedAt": "2026-03-17T12:00:00.000Z"
  },
  "meta": null,
  "error": null
}

Response Fields

Field	Type	Description
`id`	string	Workspace ID
`name`	string	Workspace display name
`isDefault`	boolean	Always `true` after this operation
`updatedAt`	string	ISO 8601 timestamp of this update

Code Examples

cURLJavaScriptPython

bash

curl -X PUT "https://api.chainabit.com/api/v1/workspaces/$WORKSPACE_ID/default" \
  -H "Authorization: Bearer $TOKEN"

javascript

const WORKSPACE_ID = process.env.WORKSPACE_ID; // id from a list or create workspace response

const response = await fetch(`${BASE_URL}/workspaces/${WORKSPACE_ID}/default`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
  },
});
const data = await response.json();

python

import os
import requests

workspace_id = os.environ["WORKSPACE_ID"]  # id from a list or create workspace response

response = requests.put(
    f"{BASE_URL}/workspaces/{workspace_id}/default",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = response.json()

PUT /workspaces/:id/active

Mark a workspace as the caller's active workspace right now. This is a UX hint, not an access-control check — it lets other signed-in devices or sessions pick up which workspace you're currently looking at on their next load. It does not affect isDefault, membership, or permissions.

Authentication: JWT Bearer token (must be a workspace member)

Request

Replace $WORKSPACE_ID below with the id from a List Workspaces or Create Workspace response.

No body.

Response

Response Example

json

{
  "data": {
    "id": "ws-abcd-efgh",
    "name": "Product Development",
    "accountId": "acc-1234-5678",
    "isActive": true,
    "isDefault": true,
    "createdAt": "2026-01-20T09:00:00.000Z"
  },
  "meta": null,
  "error": null
}

Response Fields

Field	Type	Description
`id`	string	Workspace ID
`name`	string	Workspace display name
`accountId`	string	ID of the account this workspace belongs to
`isActive`	boolean	Whether the workspace is currently active
`isDefault`	boolean	Whether this is the user's default workspace
`createdAt`	string	ISO 8601 timestamp of workspace creation

Code Examples

cURLJavaScriptPython

bash

curl -X PUT "https://api.chainabit.com/api/v1/workspaces/$WORKSPACE_ID/active" \
  -H "Authorization: Bearer $TOKEN"

javascript

const WORKSPACE_ID = process.env.WORKSPACE_ID; // id from a list or create workspace response

const response = await fetch(`${BASE_URL}/workspaces/${WORKSPACE_ID}/active`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
  },
});
const data = await response.json();

python

import os
import requests

workspace_id = os.environ["WORKSPACE_ID"]  # id from a list or create workspace response

response = requests.put(
    f"{BASE_URL}/workspaces/{workspace_id}/active",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = response.json()

Workspace Members

GET /workspaces/:id/members

List all members of a workspace.

Authentication: JWT Bearer token (must be a workspace member)

Request

Replace $WORKSPACE_ID below with the id from a List Workspaces or Create Workspace response.

Response

Response Example

json

{
  "data": [
    {
      "chainerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "username": "alice_j",
      "fullName": "Alice Johnson",
      "role": "owner",
      "joinedAt": "2026-01-20T09:00:00.000Z"
    },
    {
      "chainerId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "username": "bob_dev",
      "fullName": "Bob Smith",
      "role": "admin",
      "joinedAt": "2026-02-25T16:00:00.000Z"
    }
  ],
  "meta": {
    "total": 2
  },
  "error": null
}

Response Fields

Field	Type	Description
`chainerId`	string	Member's user ID
`username`	string	Member's username
`fullName`	string	Member's full name
`role`	string	Member's role in this workspace (`owner`, `admin`, `member`)
`joinedAt`	string	ISO 8601 timestamp of when the member joined

Code Examples

cURLJavaScriptPython

bash

curl "https://api.chainabit.com/api/v1/workspaces/$WORKSPACE_ID/members" \
  -H "Authorization: Bearer $TOKEN"

javascript

const WORKSPACE_ID = process.env.WORKSPACE_ID; // id from a list or create workspace response

const response = await fetch(`${BASE_URL}/workspaces/${WORKSPACE_ID}/members`, {
  headers: {
    Authorization: `Bearer ${TOKEN}`,
  },
});
const data = await response.json();

python

import os
import requests

workspace_id = os.environ["WORKSPACE_ID"]  # id from a list or create workspace response

response = requests.get(
    f"{BASE_URL}/workspaces/{workspace_id}/members",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = response.json()

POST /workspaces/:id/members

Add a member to a workspace. Requires owner or admin role.

Authentication: JWT Bearer token + Owner/Admin role required

Request

Replace $WORKSPACE_ID below with the id from a List Workspaces or Create Workspace response. chainerId is the user's own ID — get it from Identity / Chainers.

Field	Type	Required	Constraints	Description
`chainerId`	string	Yes	Valid user ID	ID of the user to add. Obtain this value from the Identity / Chainers endpoint.
`role`	string	Yes	`"member"` or `"admin"`	Role to assign within the workspace

Response

Response Example

json

{
  "data": {
    "chainerId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "role": "member",
    "joinedAt": "2026-03-17T11:10:00.000Z"
  },
  "meta": null,
  "error": null
}

Response Fields

Field	Type	Description
`chainerId`	string	Added member's user ID
`role`	string	Assigned role (`member` or `admin`)
`joinedAt`	string	ISO 8601 timestamp of when the member was added

Code Examples

cURLJavaScriptPython

bash

curl -X POST "https://api.chainabit.com/api/v1/workspaces/$WORKSPACE_ID/members" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chainerId": "<user-id>",
    "role": "member"
  }'

javascript

const WORKSPACE_ID = process.env.WORKSPACE_ID; // id from a list or create workspace response

const response = await fetch(`${BASE_URL}/workspaces/${WORKSPACE_ID}/members`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    chainerId: "<user-id>",
    role: "member",
  }),
});
const data = await response.json();

python

import os
import requests

workspace_id = os.environ["WORKSPACE_ID"]  # id from a list or create workspace response

response = requests.post(
    f"{BASE_URL}/workspaces/{workspace_id}/members",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={"chainerId": "<user-id>", "role": "member"},
)
data = response.json()

PATCH /workspaces/:id/members/:chainerId

Update a workspace member's role. Requires owner or admin role.

Authentication: JWT Bearer token + Owner/Admin role required

Role changes take effect immediately because the affected user's cached sessions are invalidated on the server.

Request

Replace $WORKSPACE_ID with the workspace id and $CHAINER_ID with the member's chainerId from a List Members response.

Field	Type	Required	Constraints	Description
`role`	string	Yes	`"member"` or `"admin"`	New role for the member

Response

Response Example

json

{
  "data": {
    "chainerId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "role": "admin",
    "updatedAt": "2026-03-17T11:15:00.000Z"
  },
  "meta": null,
  "error": null
}

Response Fields

Field	Type	Description
`chainerId`	string	Member's user ID
`role`	string	Updated role (`member` or `admin`)
`updatedAt`	string	ISO 8601 timestamp of this update

Code Examples

cURLJavaScriptPython

bash

curl -X PATCH "https://api.chainabit.com/api/v1/workspaces/$WORKSPACE_ID/members/$CHAINER_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'

javascript

const WORKSPACE_ID = process.env.WORKSPACE_ID; // id from a list or create workspace response
const CHAINER_ID = process.env.CHAINER_ID; // chainerId from a list-members response

const response = await fetch(
  `${BASE_URL}/workspaces/${WORKSPACE_ID}/members/${CHAINER_ID}`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ role: "admin" }),
  }
);
const data = await response.json();

python

import os
import requests

workspace_id = os.environ["WORKSPACE_ID"]  # id from a list or create workspace response
chainer_id = os.environ["CHAINER_ID"]  # chainerId from a list-members response

response = requests.patch(
    f"{BASE_URL}/workspaces/{workspace_id}/members/{chainer_id}",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={"role": "admin"},
)
data = response.json()

DELETE /workspaces/:id/members/:chainerId

Remove a member from a workspace. Requires owner or admin role.

Authentication: JWT Bearer token + Owner/Admin role required

Removals also invalidate the affected user's cached sessions immediately, so access is removed on the next request.

Request

Replace $WORKSPACE_ID with the workspace id and $CHAINER_ID with the member's chainerId from a List Members response.

Response

Response Example

json

{
  "data": {
    "chainerId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "removedAt": "2026-03-17T11:20:00.000Z"
  },
  "meta": null,
  "error": null
}

Response Fields

Field	Type	Description
`chainerId`	string	Removed member's user ID
`removedAt`	string	ISO 8601 timestamp of when the member was removed

Code Examples

cURLJavaScriptPython

bash

curl -X DELETE "https://api.chainabit.com/api/v1/workspaces/$WORKSPACE_ID/members/$CHAINER_ID" \
  -H "Authorization: Bearer $TOKEN"

javascript

const WORKSPACE_ID = process.env.WORKSPACE_ID; // id from a list or create workspace response
const CHAINER_ID = process.env.CHAINER_ID; // chainerId from a list-members response

const response = await fetch(
  `${BASE_URL}/workspaces/${WORKSPACE_ID}/members/${CHAINER_ID}`,
  {
    method: "DELETE",
    headers: {
      Authorization: `Bearer ${TOKEN}`,
    },
  }
);
const data = await response.json();

python

import os
import requests

workspace_id = os.environ["WORKSPACE_ID"]  # id from a list or create workspace response
chainer_id = os.environ["CHAINER_ID"]  # chainerId from a list-members response

response = requests.delete(
    f"{BASE_URL}/workspaces/{workspace_id}/members/{chainer_id}",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = response.json()

Workspaces ​

Workspaces ​

GET /workspaces ​

Request ​

Response ​

Response Example ​

Response Fields ​

Code Examples ​

POST /workspaces ​

Request ​

Response ​

Response Example ​

Response Fields ​

Code Examples ​

GET /workspaces/:id ​

Request ​

Response ​

Response Example ​

Response Fields ​

Code Examples ​

PATCH /workspaces/:id ​

Request ​

Response ​

Response Example ​

Response Fields ​

Code Examples ​

PATCH /workspaces/:id/activation ​

Request ​

Response ​

Response Example ​

Response Fields ​

Code Examples ​

PUT /workspaces/:id/default ​

Request ​

Response ​

Response Example ​

Response Fields ​

Code Examples ​

PUT /workspaces/:id/active ​

Request ​

Response ​

Response Example ​

Response Fields ​

Code Examples ​

Workspace Members ​

GET /workspaces/:id/members ​

Request ​

Response ​

Response Example ​

Response Fields ​

Code Examples ​

POST /workspaces/:id/members ​

Request ​

Response ​

Response Example ​

Response Fields ​

Code Examples ​

PATCH /workspaces/:id/members/:chainerId ​

Request ​

Response ​

Response Example ​

Response Fields ​

Code Examples ​

DELETE /workspaces/:id/members/:chainerId ​

Request ​

Response ​

Response Example ​

Response Fields ​

Code Examples ​

Workspaces

Workspaces

GET /workspaces

Request

Response

Response Example

Response Fields

Code Examples

POST /workspaces

Request

Response

Response Example

Response Fields

Code Examples

GET /workspaces/:id

Request

Response

Response Example

Response Fields

Code Examples

PATCH /workspaces/:id

Request

Response

Response Example

Response Fields

Code Examples

PATCH /workspaces/:id/activation

Request

Response

Response Example

Response Fields

Code Examples

PUT /workspaces/:id/default

Request

Response

Response Example

Response Fields

Code Examples

PUT /workspaces/:id/active

Request

Response

Response Example

Response Fields

Code Examples

Workspace Members

GET /workspaces/:id/members

Request

Response

Response Example

Response Fields

Code Examples

POST /workspaces/:id/members

Request

Response

Response Example

Response Fields

Code Examples

PATCH /workspaces/:id/members/:chainerId

Request

Response

Response Example

Response Fields

Code Examples

DELETE /workspaces/:id/members/:chainerId

Request

Response

Response Example

Response Fields

Code Examples