Workspaces

Endpointhttps://api.kontier.eu/v1

Workspaces of the active organization (for example a live and a sandbox workspace): list, create, read, update and delete.

List workspaces in the active organization

GET

https://api.kontier.eu/v1

/workspaces

Returns every workspace of your active organization: the live workspace first, then the sandboxes, each group by slug. From 2026-11-30 this list answers {data: [...], pagination}, like every other list.

Required scope: workspace.read (Read workspaces).

List workspaces in the active organization › Headers

X-Workspace-Id

string

Selects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.

Workspace UUID or slug.

List workspaces in the active organization › Responses

object · required

Create a workspace in the active organization

POST

https://api.kontier.eu/v1

/workspaces

Creates a sandbox workspace in your active organization. The slugs live and sandbox are reserved. An organization has exactly one live workspace, so environment must be sandbox.

Required scope: workspace.manage (Manage workspaces).

Create a workspace in the active organization › Headers

Idempotency-Key

string · required

Unique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create a workspace in the active organization › Request Body

name

string · required

The workspace's display name.

slug

string · required

The workspace's handle, unique in the organization. live and sandbox are reserved.

environment

string · enum

sandbox. Only sandbox workspaces can be created: an organization has exactly one live workspace. Required unless mode is sent.

Enum values:

live

sandbox

Create a workspace in the active organization › Responses

Created

object · required

POST/workspaces

curl --request POST \
  --url https://api.kontier.eu/v1/workspaces \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "environment": "live",
  "mode": "live",
  "name": "name",
  "slug": "slug"
}
'

shell

Example Request Body

{
  "environment": "live",
  "mode": "live",
  "name": "name",
  "slug": "slug"
}

json

Example Responses

{
  "data": {
    "active_test_clock_id": "5ce44c72-7f9f-5408-a30a-5947fe5681cb",
    "created_at": "2024-08-25T15:00:00Z",
    "environment": "live",
    "id": "4a82f969-6228-5ab1-8d01-b41ed73ee6ca",
    "mode": "live",
    "name": "name",
    "organization_id": "24d3775d-4115-5ce8-8a24-75b73041d2ca",
    "slug": "slug",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Fetch a workspace by ID or slug

GET

https://api.kontier.eu/v1

/workspaces/{id_or_slug}

Returns one workspace of your active organization, addressed by its UUID or its slug (such as live or sandbox). A workspace of another organization answers 404, the same as one that does not exist.

Required scope: workspace.read (Read workspaces).

Fetch a workspace by ID or slug › path Parameters

id_or_slug

string · required

Workspace UUID or slug

Fetch a workspace by ID or slug › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Fetch a workspace by ID or slug › Responses

object · required

Delete a workspace

DELETE

https://api.kontier.eu/v1

/workspaces/{id_or_slug}

Removes a workspace. Reserved-slug workspaces (live, sandbox) cannot be deleted - the org always has a live + sandbox pair.

Required scope: workspace.manage (Manage workspaces).

Delete a workspace › path Parameters

id_or_slug

string · required

Workspace UUID or slug

Delete a workspace › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete a workspace › Responses

No Content

No data returned

Update a workspace

PATCH

https://api.kontier.eu/v1

/workspaces/{id_or_slug}

Changes the workspace's name. Slug and environment cannot be changed. To restrict what an organization may do, place a restriction on the organization itself.

Required scope: workspace.manage (Manage workspaces).

Update a workspace › path Parameters

id_or_slug

string · required

Workspace UUID or slug

Update a workspace › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a workspace › Request Body

name

string

Update a workspace › Responses

object · required

Organizations Roles

List workspaces in the active organization

GET

https://api.kontier.eu/v1

/workspaces

Required scope: workspace.read (Read workspaces).

List workspaces in the active organization › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List workspaces in the active organization › Responses

object · required

Create a workspace in the active organization

POST

https://api.kontier.eu/v1

/workspaces

Creates a sandbox workspace in your active organization. The slugs live and sandbox are reserved. An organization has exactly one live workspace, so environment must be sandbox.

Required scope: workspace.manage (Manage workspaces).

Create a workspace in the active organization › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create a workspace in the active organization › Request Body

name

string · required

The workspace's display name.

slug

string · required

The workspace's handle, unique in the organization. live and sandbox are reserved.

environment

string · enum

sandbox. Only sandbox workspaces can be created: an organization has exactly one live workspace. Required unless mode is sent.

Enum values:

live

sandbox

Create a workspace in the active organization › Responses

Created

object · required

Fetch a workspace by ID or slug

GET

https://api.kontier.eu/v1

/workspaces/{id_or_slug}

Returns one workspace of your active organization, addressed by its UUID or its slug (such as live or sandbox). A workspace of another organization answers 404, the same as one that does not exist.

Required scope: workspace.read (Read workspaces).

Fetch a workspace by ID or slug › path Parameters

id_or_slug

string · required

Workspace UUID or slug

Fetch a workspace by ID or slug › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Fetch a workspace by ID or slug › Responses

object · required

Delete a workspace

DELETE

https://api.kontier.eu/v1

/workspaces/{id_or_slug}

Removes a workspace. Reserved-slug workspaces (live, sandbox) cannot be deleted - the org always has a live + sandbox pair.

Required scope: workspace.manage (Manage workspaces).

Delete a workspace › path Parameters

id_or_slug

string · required

Workspace UUID or slug

Delete a workspace › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete a workspace › Responses

No Content

No data returned

Update a workspace

PATCH

https://api.kontier.eu/v1

/workspaces/{id_or_slug}

Changes the workspace's name. Slug and environment cannot be changed. To restrict what an organization may do, place a restriction on the organization itself.

Required scope: workspace.manage (Manage workspaces).

Update a workspace › path Parameters

id_or_slug

string · required

Workspace UUID or slug

Update a workspace › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a workspace › Request Body

name

string

Update a workspace › Responses

object · required