Workspace service#

This service provides information about workspaces. Workspaces provide access control boundaries. All resources in Nominal live within a workspace.

OpenAPI file: WorkspaceService.json

Endpoints#

Get workspaces#

GET /workspaces/v1/workspaces

Gets all workspaces that the requesting user belongs to. Filters results to workspaces in the user’s session org, unless otherwise specified.

Query parameters

filterBySessionOrg boolean: When true (the default), returns only workspaces in the caller’s session org. When false, returns workspaces across all orgs the user belongs to.
includeGuestWorkspaces boolean: When true, includes workspaces where the user matches a guest condition. When false (the default), returns only workspaces where the user is a full member.

Response

The body is an array of Workspace.

Fields of Workspace

id string

A unique identifier for the workspace within the organization. The workspace ID must be lower case alphanumeric characters, optionally separated by hyphens.

rid string (RID)

org string (RID)

displayName string

symbol WorkspaceSymbol

icon

Set type to "icon".

icon string: Workspace icon name (e.g. castle)

emoji

Set type to "emoji".

emoji string: Workspace emoji name (e.g. :castle:)

image

Set type to "image".

image string: Workspace image url (e.g. https://example.com/image.png)

settings WorkspaceSettings

Fields of WorkspaceSettings

refNames PreferredRefNameConfiguration

Set type to "v1".

v1 array of RefNameAndType

Fields of RefNameAndType

name string

type DataSourceType

Values of DataSourceType

DATASET
CONNECTION
VIDEO
SPATIAL

procedures ProcedureSettings

Set type to "v1".

v1 ProcedureSettingsV1

Fields of ProcedureSettingsV1

workspaceProcedures array of string (RID): A list of procedures that are elevated to the workspace-level. They will be available for execution in a top-level context, rather than just from the procedure details page.

Request

curl

curl "https://api.gov.nominal.io/api/workspaces/v1/workspaces" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/workspaces/v1/workspaces",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/workspaces/v1/workspaces",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/workspaces/v1/workspaces",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

[
  {
    "id": "<workspace id>",
    "rid": "<workspace rid>",
    "org": "<org rid>",
    "displayName": "<display name>",
    "symbol": {
      "type": "icon",
      "icon": "<icon>"
    },
    "settings": {
      "refNames": {
        "type": "v1",
        "v1": [
          {
            "name": "<data source ref name>",
            "type": "DATASET"
          }
        ]
      },
      "procedures": {
        "type": "v1",
        "v1": {
          "workspaceProcedures": [
            "<procedure rid>"
          ]
        }
      }
    }
  }
]

Get workspace#

GET /workspaces/v1/workspaces/{workspaceRid}

Gets the workspace with the specified WorkspaceRid. Throws if the requesting user does not have access to the workspace based on their current session.

Path parameters

workspaceRid string (RID) required

Response

id string

A unique identifier for the workspace within the organization. The workspace ID must be lower case alphanumeric characters, optionally separated by hyphens.

rid string (RID)

org string (RID)

displayName string

symbol WorkspaceSymbol

icon

Set type to "icon".

icon string: Workspace icon name (e.g. castle)

emoji

Set type to "emoji".

emoji string: Workspace emoji name (e.g. :castle:)

image

Set type to "image".

image string: Workspace image url (e.g. https://example.com/image.png)

settings WorkspaceSettings

Fields of WorkspaceSettings

refNames PreferredRefNameConfiguration

Set type to "v1".

v1 array of RefNameAndType

Fields of RefNameAndType

name string

type DataSourceType

Values of DataSourceType

DATASET
CONNECTION
VIDEO
SPATIAL

procedures ProcedureSettings

Set type to "v1".

v1 ProcedureSettingsV1

Fields of ProcedureSettingsV1

workspaceProcedures array of string (RID): A list of procedures that are elevated to the workspace-level. They will be available for execution in a top-level context, rather than just from the procedure details page.

Request

curl

curl "https://api.gov.nominal.io/api/workspaces/v1/workspaces/<workspace rid>" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/workspaces/v1/workspaces/<workspace rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/workspaces/v1/workspaces/<workspace rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/workspaces/v1/workspaces/<workspace rid>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "id": "<workspace id>",
  "rid": "<workspace rid>",
  "org": "<org rid>",
  "displayName": "<display name>",
  "symbol": {
    "type": "icon",
    "icon": "<icon>"
  },
  "settings": {
    "refNames": {
      "type": "v1",
      "v1": [
        {
          "name": "<data source ref name>",
          "type": "DATASET"
        }
      ]
    },
    "procedures": {
      "type": "v1",
      "v1": {
        "workspaceProcedures": [
          "<procedure rid>"
        ]
      }
    }
  }
}

Get default workspace#

GET /workspaces/v1/default-workspace

Gets the default workspace for the requesting user. If the user belongs to a single workspace, that workspace is returned. Otherwise, if the user’s organization has a default workspace and the user belongs to it, that will be returned.

Request

No parameters and no body.

Response

id string

A unique identifier for the workspace within the organization. The workspace ID must be lower case alphanumeric characters, optionally separated by hyphens.

rid string (RID)

org string (RID)

displayName string

symbol WorkspaceSymbol

icon

Set type to "icon".

icon string: Workspace icon name (e.g. castle)

emoji

Set type to "emoji".

emoji string: Workspace emoji name (e.g. :castle:)

image

Set type to "image".

image string: Workspace image url (e.g. https://example.com/image.png)

settings WorkspaceSettings

Fields of WorkspaceSettings

refNames PreferredRefNameConfiguration

Set type to "v1".

v1 array of RefNameAndType

Fields of RefNameAndType

name string

type DataSourceType

Values of DataSourceType

DATASET
CONNECTION
VIDEO
SPATIAL

procedures ProcedureSettings

Set type to "v1".

v1 ProcedureSettingsV1

Fields of ProcedureSettingsV1

workspaceProcedures array of string (RID): A list of procedures that are elevated to the workspace-level. They will be available for execution in a top-level context, rather than just from the procedure details page.

When there is nothing to return, the response is HTTP 204 with no body.

Request

curl

curl "https://api.gov.nominal.io/api/workspaces/v1/default-workspace" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/workspaces/v1/default-workspace",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/workspaces/v1/default-workspace",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/workspaces/v1/default-workspace",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "id": "<workspace id>",
  "rid": "<workspace rid>",
  "org": "<org rid>",
  "displayName": "<display name>",
  "symbol": {
    "type": "icon",
    "icon": "<icon>"
  },
  "settings": {
    "refNames": {
      "type": "v1",
      "v1": [
        {
          "name": "<data source ref name>",
          "type": "DATASET"
        }
      ]
    },
    "procedures": {
      "type": "v1",
      "v1": {
        "workspaceProcedures": [
          "<procedure rid>"
        ]
      }
    }
  }
}

Errors#

Errors shows how these errors are sent.

Each error’s errorName is Security: followed by its name below.

Status	Name	Notes
400	`ForbiddenCrossWorkspaceOperation`	Workspaces are hard boundaries in Nominal. Resources from different workspaces cannot be combined.
400	`WorkspaceNotSpecified`	A workspace was not specified and could not be inferred.
404	`WorkspaceNotFound`	The workspace with the specified rid was not found.

Types#

DataSourceType#

DATASET
CONNECTION
VIDEO
SPATIAL

PreferredRefNameConfiguration#

Set type to the name of one of the other fields, and set only that field.

v1 array of RefNameAndType

ProcedureSettings#

Set type to the name of one of the other fields, and set only that field.

v1 ProcedureSettingsV1

ProcedureSettingsV1#

workspaceProcedures array of string (RID): A list of procedures that are elevated to the workspace-level. They will be available for execution in a top-level context, rather than just from the procedure details page.

RefNameAndType#

name string required
type DataSourceType required

RemoveType#

The request to remove a field from a workspace.

An empty JSON object, {}.

UpdateOrRemoveWorkspaceDisplayName#

The request to update the display name of the workspace. The request will replace the existing display name with the display name specified if it’s provided. Otherwise, the current display name will be removed from the workspace.

Set type to the name of one of the other fields, and set only that field.

displayName string
removeType RemoveType

UpdateOrRemoveWorkspaceSymbol#

The request to update the symbol of the workspace. The request will replace the existing symbol with the symbol specified if it’s provided. Otherwise, the current symbol will be removed from the workspace.

Set type to the name of one of the other fields, and set only that field.

symbol WorkspaceSymbol
removeType RemoveType

Workspace#

id string required: A unique identifier for the workspace within the organization. The workspace ID must be lower case alphanumeric characters, optionally separated by hyphens.
rid string (RID) required
org string (RID) required
displayName string
symbol WorkspaceSymbol
settings WorkspaceSettings required

WorkspaceSettings#

refNames PreferredRefNameConfiguration
procedures ProcedureSettings

WorkspaceSymbol#

Set type to the name of one of the other fields, and set only that field.

icon string: Workspace icon name (e.g. castle)
emoji string: Workspace emoji name (e.g. :castle:)
image string: Workspace image url (e.g. https://example.com/image.png)

Page design based on Scalar, MIT License.

Workspace service#

Endpoints#

Get workspaces#

Get workspace#

Update workspace#

Get default workspace#

Errors#

Types#

DataSourceType#

PreferredRefNameConfiguration#

ProcedureSettings#

ProcedureSettingsV1#

RefNameAndType#

RemoveType#

UpdateOrRemoveWorkspaceDisplayName#

UpdateOrRemoveWorkspaceSymbol#

Workspace#

WorkspaceSettings#

WorkspaceSymbol#