{
  "swagger": "2.0",
  "info": {
    "title": "Workspace service",
    "version": "0.1507.0",
    "description": "Send your API key as a bearer token: `Authorization: Bearer <api key>`."
  },
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "securityDefinitions": {
    "ApiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "Authorization",
      "description": "Your API key as a bearer token: `Authorization: Bearer <api key>`."
    }
  },
  "security": [
    {
      "ApiKey": []
    }
  ],
  "paths": {
    "/workspaces/v1/workspaces": {
      "get": {
        "operationId": "WorkspaceService_getWorkspaces",
        "summary": "Get workspaces",
        "tags": [
          "Workspace Service"
        ],
        "description": "Gets all workspaces that the requesting user belongs to. Filters results to workspaces in the user's session org, unless otherwise specified.",
        "parameters": [
          {
            "name": "filterBySessionOrg",
            "in": "query",
            "type": "boolean",
            "required": false,
            "description": "When true (the default), returns only workspaces in the caller's session org. When false, returns workspaces across all orgs the user belongs to."
          },
          {
            "name": "includeGuestWorkspaces",
            "in": "query",
            "type": "boolean",
            "required": false,
            "description": "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."
          }
        ],
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Workspace"
              },
              "uniqueItems": true
            },
            "x-example": [
              {
                "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>"
                      ]
                    }
                  }
                }
              }
            ]
          }
        }
      }
    },
    "/workspaces/v1/workspaces/{workspaceRid}": {
      "get": {
        "operationId": "WorkspaceService_getWorkspace",
        "summary": "Get workspace",
        "tags": [
          "Workspace Service"
        ],
        "description": "Gets the workspace with the specified WorkspaceRid. Throws if the requesting user does not have access to the workspace based on their current session.",
        "parameters": [
          {
            "name": "workspaceRid",
            "in": "path",
            "type": "string",
            "format": "rid",
            "x-alias": "WorkspaceRid",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/Workspace"
            },
            "x-example": {
              "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>"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/v1/workspaces/{rid}": {
      "put": {
        "operationId": "WorkspaceService_updateWorkspace",
        "summary": "Update workspace",
        "tags": [
          "Workspace Service"
        ],
        "description": "Updates the settings of the workspace with the specified WorkspaceRid.",
        "parameters": [
          {
            "name": "rid",
            "in": "path",
            "type": "string",
            "format": "rid",
            "x-alias": "WorkspaceRid",
            "required": true
          },
          {
            "name": "request",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/UpdateWorkspaceRequest"
            },
            "required": true,
            "x-example": {
              "displayName": {
                "type": "displayName",
                "displayName": "<display name>"
              },
              "symbol": {
                "type": "symbol",
                "symbol": {
                  "type": "icon",
                  "icon": "<icon>"
                }
              },
              "settings": {
                "refNames": {
                  "type": "v1",
                  "v1": [
                    {
                      "name": "<data source ref name>",
                      "type": "DATASET"
                    }
                  ]
                },
                "procedures": {
                  "type": "v1",
                  "v1": {
                    "workspaceProcedures": [
                      "<procedure rid>"
                    ]
                  }
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/Workspace"
            },
            "x-example": {
              "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>"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/v1/default-workspace": {
      "get": {
        "operationId": "WorkspaceService_getDefaultWorkspace",
        "summary": "Get default workspace",
        "tags": [
          "Workspace Service"
        ],
        "description": "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.",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/Workspace"
            },
            "x-example": {
              "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>"
                    ]
                  }
                }
              }
            }
          },
          "204": {
            "description": "No content, when there is nothing to return."
          }
        }
      }
    }
  },
  "definitions": {
    "DataSourceType": {
      "type": "string",
      "enum": [
        "DATASET",
        "CONNECTION",
        "VIDEO",
        "SPATIAL"
      ]
    },
    "RefNameAndType": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "x-alias": "DataSourceRefName"
        },
        "type": {
          "$ref": "#/definitions/DataSourceType"
        }
      },
      "required": [
        "name",
        "type"
      ]
    },
    "PreferredRefNameConfiguration": {
      "type": "object",
      "x-union": true,
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "v1"
          ]
        },
        "v1": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/RefNameAndType"
          }
        }
      },
      "required": [
        "type"
      ],
      "description": "Set `type` to the name of one of the other fields, and set only that field.",
      "example": {
        "type": "v1",
        "v1": [
          {
            "name": "string",
            "type": "DATASET"
          }
        ]
      }
    },
    "ProcedureSettings": {
      "type": "object",
      "x-union": true,
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "v1"
          ]
        },
        "v1": {
          "$ref": "#/definitions/ProcedureSettingsV1"
        }
      },
      "required": [
        "type"
      ],
      "description": "Set `type` to the name of one of the other fields, and set only that field.",
      "example": {
        "type": "v1",
        "v1": {
          "workspaceProcedures": [
            "string"
          ]
        }
      }
    },
    "ProcedureSettingsV1": {
      "type": "object",
      "properties": {
        "workspaceProcedures": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "rid",
            "x-alias": "ProcedureRid"
          },
          "description": "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."
        }
      }
    },
    "RemoveType": {
      "description": "The request to remove a field from a workspace.",
      "type": "object",
      "properties": {}
    },
    "UpdateOrRemoveWorkspaceDisplayName": {
      "description": "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.\n\nSet `type` to the name of one of the other fields, and set only that field.",
      "type": "object",
      "x-union": true,
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "displayName",
            "removeType"
          ]
        },
        "displayName": {
          "type": "string"
        },
        "removeType": {
          "$ref": "#/definitions/RemoveType"
        }
      },
      "required": [
        "type"
      ],
      "example": {
        "type": "displayName",
        "displayName": "string"
      }
    },
    "UpdateOrRemoveWorkspaceSymbol": {
      "description": "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.\n\nSet `type` to the name of one of the other fields, and set only that field.",
      "type": "object",
      "x-union": true,
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "symbol",
            "removeType"
          ]
        },
        "symbol": {
          "$ref": "#/definitions/WorkspaceSymbol"
        },
        "removeType": {
          "$ref": "#/definitions/RemoveType"
        }
      },
      "required": [
        "type"
      ],
      "example": {
        "type": "symbol",
        "symbol": {
          "type": "icon",
          "icon": "string"
        }
      }
    },
    "UpdateWorkspaceRequest": {
      "type": "object",
      "properties": {
        "displayName": {
          "$ref": "#/definitions/UpdateOrRemoveWorkspaceDisplayName"
        },
        "symbol": {
          "$ref": "#/definitions/UpdateOrRemoveWorkspaceSymbol"
        },
        "settings": {
          "$ref": "#/definitions/WorkspaceSettings"
        }
      },
      "example": {
        "displayName": {
          "type": "displayName",
          "displayName": "<display name>"
        },
        "symbol": {
          "type": "symbol",
          "symbol": {
            "type": "icon",
            "icon": "<icon>"
          }
        },
        "settings": {
          "refNames": {
            "type": "v1",
            "v1": [
              {
                "name": "<data source ref name>",
                "type": "DATASET"
              }
            ]
          },
          "procedures": {
            "type": "v1",
            "v1": {
              "workspaceProcedures": [
                "<procedure rid>"
              ]
            }
          }
        }
      }
    },
    "Workspace": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "x-alias": "WorkspaceId",
          "description": "A unique identifier for the workspace within the organization. The workspace ID must be lower case alphanumeric characters, optionally separated by hyphens."
        },
        "rid": {
          "type": "string",
          "format": "rid",
          "x-alias": "WorkspaceRid"
        },
        "org": {
          "type": "string",
          "format": "rid",
          "x-alias": "OrgRid"
        },
        "displayName": {
          "type": "string"
        },
        "symbol": {
          "$ref": "#/definitions/WorkspaceSymbol"
        },
        "settings": {
          "$ref": "#/definitions/WorkspaceSettings"
        }
      },
      "required": [
        "id",
        "rid",
        "org",
        "settings"
      ]
    },
    "WorkspaceSettings": {
      "type": "object",
      "properties": {
        "refNames": {
          "$ref": "#/definitions/PreferredRefNameConfiguration"
        },
        "procedures": {
          "$ref": "#/definitions/ProcedureSettings"
        }
      }
    },
    "WorkspaceSymbol": {
      "type": "object",
      "x-union": true,
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "icon",
            "emoji",
            "image"
          ]
        },
        "icon": {
          "type": "string",
          "description": "Workspace icon name (e.g. castle)"
        },
        "emoji": {
          "type": "string",
          "description": "Workspace emoji name (e.g. :castle:)"
        },
        "image": {
          "type": "string",
          "description": "Workspace image url (e.g. https://example.com/image.png)"
        }
      },
      "required": [
        "type"
      ],
      "description": "Set `type` to the name of one of the other fields, and set only that field.",
      "example": {
        "type": "icon",
        "icon": "string"
      }
    }
  },
  "tags": [
    {
      "name": "Workspace Service",
      "x-displayName": "Workspace service",
      "description": "This service provides information about workspaces. Workspaces provide access control boundaries. All resources in Nominal live within a workspace.",
      "x-errors": [
        {
          "status": 400,
          "errorCode": "INVALID_ARGUMENT",
          "errorName": "Security:ForbiddenCrossWorkspaceOperation",
          "description": "Workspaces are hard boundaries in Nominal. Resources from different workspaces cannot be combined."
        },
        {
          "status": 400,
          "errorCode": "INVALID_ARGUMENT",
          "errorName": "Security:WorkspaceNotSpecified",
          "description": "A workspace was not specified and could not be inferred."
        },
        {
          "status": 404,
          "errorCode": "NOT_FOUND",
          "errorName": "Security:WorkspaceNotFound",
          "description": "The workspace with the specified rid was not found."
        }
      ]
    }
  ]
}