Workspaces

Workspaces enable Krenalis to retrieve customer and event data from an external source location or send them to an external destination location.

Create workspace

Creates a new workspace.

Request

  • name

    string Required

    The workspace's name.

    Must be a non-empty string with a maximum of 100 characters.

  • profileSchema

    schema Required

    The profile schema, defining the structure and properties of a profile of the workspace.

  • warehouse

    object Required

    The data warehouse of the workspace, serving as the central repository for the workspace's user data and collected events.

    As part of the workspace provisioning process, the specified database is initialized with the schema, including all necessary tables, views, and stored procedures. The target database must be empty prior to initialization.

    • warehouse.platform

      string Required

      The data warehouse platform. By default, Krenalis includes PostgreSQL and Snowflake.

    • warehouse.mode

      string

      The mode of the data warehouse. If not specified, the default is "Normal".

      Possible values: "Normal", "Inspection" or "Maintenance".

    • warehouse.settings

      object with json values Required

      The settings of the data warehouse.

      PostgreSQL

      • host

        string Required : Hostname or IP address of the server.

      • port

        int Required : Port number.

      • username

        string Required : Username.

      • password

        string : Password.

      • database

        string Required : Name of the database.

      • schema

        string Required : Name of the schema within the database.

      Snowflake

      • account

        string Required : Account identifier.

      • username

        string Required : Username.

      • password

        string Required : Password.

      • role

        string Required : Role that will be used for accessing the data.

      • database

        string Required : Name of the database.

      • schema

        string Required : Name of the schema within the database.

      • warehouse

        string Required : Name of the virtual warehouse.

  • uiPreferences

    object

    • uiPreferences.userProfile

      object

      • uiPreferences.userProfile.image

        string

        The path of the property in the profile schema that represents the user's image, in base64 format.

        It cannot be longer than 100 characters.

      • uiPreferences.userProfile.firstName

        string

        The path of the property in the profile schema to display as the first name in the profile header.

        It cannot be longer than 100 characters.

      • uiPreferences.userProfile.lastName

        string

        The path of the property in the profile schema for the user's last name.

        It cannot be longer than 100 characters.

      • uiPreferences.userProfile.extra

        string

        The path of the property in the profile schema for additional user information. For example, the profile schema property that represents the email.

        It cannot be longer than 100 characters.

Response

  • id

    int

    The ID of the workspace.
POST /v1/workspaces
curl https://example.com/v1/workspaces \
-H "Authorization: Bearer api_xxxxxxx" \
--json '{
"name": "Customers",
"profileSchema": {
"kind": "object",
"properties": [
{
"name": "customer_id",
"type": {
"kind": "string",
"maxLength": 36
},
"readOptional": true,
"description": "Customer ID"
},
{
"name": "first_name",
"type": {
"kind": "string",
"maxLength": 100
},
"readOptional": true,
"description": "First name"
},
{
"name": "last_name",
"type": {
"kind": "string",
"maxLength": 100
},
"readOptional": true,
"description": "Last name"
},
{
"name": "email",
"type": {
"kind": "string",
"maxLength": 254
},
"readOptional": true,
"description": "Email"
},
{
"name": "phone_number",
"type": {
"kind": "string",
"maxLength": 20
},
"readOptional": true,
"description": "Phone number"
},
{
"name": "birth_date",
"type": {
"kind": "date"
},
"readOptional": true,
"description": "Birth date"
},
{
"name": "gender",
"type": {
"kind": "string"
},
"readOptional": true,
"description": "Gender"
},
{
"name": "address",
"type": {
"kind": "object",
"properties": [
{
"name": "street",
"type": {
"kind": "string",
"maxLength": 255
},
"readOptional": true,
"description": "Street"
},
{
"name": "city",
"type": {
"kind": "string",
"maxLength": 100
},
"readOptional": true,
"description": "City"
},
{
"name": "postal_code",
"type": {
"kind": "string",
"maxLength": 20
},
"readOptional": true,
"description": "Postal code"
},
{
"name": "country",
"type": {
"kind": "string",
"maxLength": 2
},
"readOptional": true,
"description": "Country"
}
]
},
"readOptional": true,
"description": "Address"
},
{
"name": "preferences",
"type": {
"kind": "object",
"properties": [
{
"name": "newsletter",
"type": {
"kind": "boolean"
},
"readOptional": true,
"description": "Newsletter subscription"
},
{
"name": "categories",
"type": {
"kind": "array",
"elementType": {
"kind": "string"
}
},
"readOptional": true,
"description": "Preferences categories"
},
{
"name": "language",
"type": {
"kind": "string",
"maxLength": 2
},
"readOptional": true,
"description": "Language"
}
]
},
"readOptional": true,
"description": "Preferences"
}
]
},
"warehouse": {
"platform": "Snowflake",
"mode": "Normal",
"settings": {
"account": "ABCDEFG-TUVWXYZ",
"username": "USERNAME",
"password": "password",
"role": "CUSTOM_ROLE",
"database": "MY_DATABASE",
"schema": "PUBLIC",
"warehouse": "COMPUTE_WH"
}
},
"uiPreferences": {
"userProfile": {
"firstName": "first_name",
"lastName": "last_name",
"extra": "email"
}
}
}'
Response
{
  "id": 1371036433
}
Errors
422
warehouse platform does not exist
422
data warehouse settings are not valid
422
data warehouse cannot be initialized

Test workspace creation

Checks the process of creating a new workspace. It performs all the validations required for workspace creation, including verifying that the data warehouse can be initialized, without making any changes to the data warehouse or actually creating the workspace.

Request

  • name

    string Required

    The workspace's name.

    Must be a non-empty string with a maximum of 100 characters.

  • profileSchema

    schema Required

    The profile schema, defining the structure and properties of a profile of the workspace.

  • warehouse

    object Required

    The data warehouse of the workspace, serving as the central repository for the workspace's user data and collected events.

    Since this method only tests the creation of a workspace, the data warehouse is not modified. The target database must be empty to make the check succeed.

    • warehouse.platform

      string Required

      The data warehouse platform. By default, Krenalis includes PostgreSQL and Snowflake.

    • warehouse.mode

      string

      The mode of the data warehouse. If not specified, the default is "Normal".

      Possible values: "Normal", "Inspection" or "Maintenance".

    • warehouse.settings

      object with json values Required

      The settings of the data warehouse.

      PostgreSQL

      • host

        string Required : Hostname or IP address of the server.

      • port

        int Required : Port number.

      • username

        string Required : Username.

      • password

        string : Password.

      • database

        string Required : Name of the database.

      • schema

        string Required : Name of the schema within the database.

      Snowflake

      • account

        string Required : Account identifier.

      • username

        string Required : Username.

      • password

        string Required : Password.

      • role

        string Required : Role that will be used for accessing the data.

      • database

        string Required : Name of the database.

      • schema

        string Required : Name of the schema within the database.

      • warehouse

        string Required : Name of the virtual warehouse.

  • uiPreferences

    object

    • uiPreferences.userProfile

      object

      • uiPreferences.userProfile.image

        string

        The path of the property in the profile schema that represents the user's image, in base64 format.

        It cannot be longer than 100 characters.

      • uiPreferences.userProfile.firstName

        string

        The path of the property in the profile schema to display as the first name in the profile header.

        It cannot be longer than 100 characters.

      • uiPreferences.userProfile.lastName

        string

        The path of the property in the profile schema for the user's last name.

        It cannot be longer than 100 characters.

      • uiPreferences.userProfile.extra

        string

        The path of the property in the profile schema for additional user information. For example, the profile schema property that represents the email.

        It cannot be longer than 100 characters.

Response

No response.
POST /v1/workspaces/test
curl https://example.com/v1/workspaces/test \
-H "Authorization: Bearer api_xxxxxxx" \
--json '{
"name": "Customers",
"profileSchema": {
"kind": "object",
"properties": [
{
"name": "customer_id",
"type": {
"kind": "string",
"maxLength": 36
},
"readOptional": true,
"description": "Customer ID"
},
{
"name": "first_name",
"type": {
"kind": "string",
"maxLength": 100
},
"readOptional": true,
"description": "First name"
},
{
"name": "last_name",
"type": {
"kind": "string",
"maxLength": 100
},
"readOptional": true,
"description": "Last name"
},
{
"name": "email",
"type": {
"kind": "string",
"maxLength": 254
},
"readOptional": true,
"description": "Email"
},
{
"name": "phone_number",
"type": {
"kind": "string",
"maxLength": 20
},
"readOptional": true,
"description": "Phone number"
},
{
"name": "birth_date",
"type": {
"kind": "date"
},
"readOptional": true,
"description": "Birth date"
},
{
"name": "gender",
"type": {
"kind": "string"
},
"readOptional": true,
"description": "Gender"
},
{
"name": "address",
"type": {
"kind": "object",
"properties": [
{
"name": "street",
"type": {
"kind": "string",
"maxLength": 255
},
"readOptional": true,
"description": "Street"
},
{
"name": "city",
"type": {
"kind": "string",
"maxLength": 100
},
"readOptional": true,
"description": "City"
},
{
"name": "postal_code",
"type": {
"kind": "string",
"maxLength": 20
},
"readOptional": true,
"description": "Postal code"
},
{
"name": "country",
"type": {
"kind": "string",
"maxLength": 2
},
"readOptional": true,
"description": "Country"
}
]
},
"readOptional": true,
"description": "Address"
},
{
"name": "preferences",
"type": {
"kind": "object",
"properties": [
{
"name": "newsletter",
"type": {
"kind": "boolean"
},
"readOptional": true,
"description": "Newsletter subscription"
},
{
"name": "categories",
"type": {
"kind": "array",
"elementType": {
"kind": "string"
}
},
"readOptional": true,
"description": "Preferences categories"
},
{
"name": "language",
"type": {
"kind": "string",
"maxLength": 2
},
"readOptional": true,
"description": "Language"
}
]
},
"readOptional": true,
"description": "Preferences"
}
]
},
"warehouse": {
"platform": "Snowflake",
"mode": "Normal",
"settings": {
"account": "ABCDEFG-TUVWXYZ",
"username": "USERNAME",
"password": "password",
"role": "CUSTOM_ROLE",
"database": "MY_DATABASE",
"schema": "PUBLIC",
"warehouse": "COMPUTE_WH"
}
},
"uiPreferences": {
"userProfile": {
"firstName": "first_name",
"lastName": "last_name",
"extra": "email"
}
}
}'
Errors
422
warehouse platform does not exist
422
data warehouse settings are not valid
422
data warehouse cannot be initialized

Update workspace

Updates the current workspace.

The current workspace is the workspace associated with the API key (if it is a restricted key) or the one specified via the Krenalis-Workspace header. For more details, see the authentication documentation.

Request

  • name

    string Required

    The workspace's name.

    Must be a non-empty string with a maximum of 100 characters.

  • uiPreferences

    object

    • uiPreferences.userProfile

      object

      • uiPreferences.userProfile.image

        string

        The path of the property in the profile schema that represents the user's image, in base64 format.

        It cannot be longer than 100 characters.

      • uiPreferences.userProfile.firstName

        string

        The path of the property in the profile schema to display as the first name in the profile header.

        It cannot be longer than 100 characters.

      • uiPreferences.userProfile.lastName

        string

        The path of the property in the profile schema for the user's last name.

        It cannot be longer than 100 characters.

      • uiPreferences.userProfile.extra

        string

        The path of the property in the profile schema for additional user information. For example, the profile schema property that represents the email.

        It cannot be longer than 100 characters.

Response

No response.
PUT /v1/workspaces/current
curl -X PUT https://example.com/v1/workspaces/current \
-H "Authorization: Bearer api_xxxxxxx" \
--json '{
"name": "Customers",
"uiPreferences": {
"userProfile": {
"firstName": "first_name",
"lastName": "last_name",
"extra": "email"
}
}
}'
Errors
404
workspace does not exist

List all workspaces

Lists all the workspaces.

Request

No parameters.

Response

  • workspaces

    array of object

    The workspaces.

    • id

      int

      The ID of the workspace.

    • name

      string

      The workspace's name.

      It is not longer than 100 characters.

    • profileSchema

      schema

      The profile schema, defining the structure and properties of a profile of the workspace.

    • primarySources

      object with int values

      The primary source for each profile schema property that has one, where the key is the property name and the value is the connection identifier.

      This source defines where the definitive value for the property is read from, preventing other sources from overwriting it once it is set.

    • resolveIdentitiesOnBatchImport

      boolean

      Indicates whether identity resolution should be performed immediately after a batch import.

      If set to true, Krenalis will automatically resolve identities as soon as the import is finished. If set to false, identity resolution will not happen automatically and will need to be triggered separately.

    • identifiers

      array of string

      The profile schema properties used to determine if two users are the same. The identity resolution checks these identities in order. Two users are considered the same if they have the same value for the first identity, or if neither user has a value for the first identity, the identity resolution moves to the next one, and so on.

      If no identifiers are specified, once identity resolution is performed, all users will be considered different from each other.

    • mode

      string

      The mode of the data warehouse. If not specified, the default is "Normal".

      Possible values: "Normal", "Inspection" or "Maintenance".

    • uiPreferences

      object

      • uiPreferences.userProfile

        object

        • uiPreferences.userProfile.image

          string

          The path of the property in the profile schema that represents the user's image, in base64 format.

          It is not longer than 100 characters.

        • uiPreferences.userProfile.firstName

          string

          The path of the property in the profile schema to display as the first name in the profile header.

          It is not longer than 100 characters.

        • uiPreferences.userProfile.lastName

          string

          The path of the property in the profile schema for the user's last name.

          It is not longer than 100 characters.

        • uiPreferences.userProfile.extra

          string

          The path of the property in the profile schema for additional user information. For example, the profile schema property that represents the email.

          It is not longer than 100 characters.
GET /v1/workspaces
curl https://example.com/v1/workspaces \
-H "Authorization: Bearer api_xxxxxxx"
Response
{
  "workspaces": [
    {
      "id": 1371036433,
      "name": "Customers",
      "profileSchema": {
        "kind": "object",
        "properties": [
          {
            "name": "customer_id",
            "type": {
              "kind": "string",
              "maxLength": 36
            },
            "readOptional": true,
            "description": "Customer ID"
          },
          {
            "name": "first_name",
            "type": {
              "kind": "string",
              "maxLength": 100
            },
            "readOptional": true,
            "description": "First name"
          },
          {
            "name": "last_name",
            "type": {
              "kind": "string",
              "maxLength": 100
            },
            "readOptional": true,
            "description": "Last name"
          },
          {
            "name": "email",
            "type": {
              "kind": "string",
              "maxLength": 254
            },
            "readOptional": true,
            "description": "Email"
          },
          {
            "name": "phone_number",
            "type": {
              "kind": "string",
              "maxLength": 20
            },
            "readOptional": true,
            "description": "Phone number"
          },
          {
            "name": "birth_date",
            "type": {
              "kind": "date"
            },
            "readOptional": true,
            "description": "Birth date"
          },
          {
            "name": "gender",
            "type": {
              "kind": "string"
            },
            "readOptional": true,
            "description": "Gender"
          },
          {
            "name": "address",
            "type": {
              "kind": "object",
              "properties": [
                {
                  "name": "street",
                  "type": {
                    "kind": "string",
                    "maxLength": 255
                  },
                  "readOptional": true,
                  "description": "Street"
                },
                {
                  "name": "city",
                  "type": {
                    "kind": "string",
                    "maxLength": 100
                  },
                  "readOptional": true,
                  "description": "City"
                },
                {
                  "name": "postal_code",
                  "type": {
                    "kind": "string",
                    "maxLength": 20
                  },
                  "readOptional": true,
                  "description": "Postal code"
                },
                {
                  "name": "country",
                  "type": {
                    "kind": "string",
                    "maxLength": 2
                  },
                  "readOptional": true,
                  "description": "Country"
                }
              ]
            },
            "readOptional": true,
            "description": "Address"
          },
          {
            "name": "preferences",
            "type": {
              "kind": "object",
              "properties": [
                {
                  "name": "newsletter",
                  "type": {
                    "kind": "boolean"
                  },
                  "readOptional": true,
                  "description": "Newsletter subscription"
                },
                {
                  "name": "categories",
                  "type": {
                    "kind": "array",
                    "elementType": {
                      "kind": "string"
                    }
                  },
                  "readOptional": true,
                  "description": "Preferences categories"
                },
                {
                  "name": "language",
                  "type": {
                    "kind": "string",
                    "maxLength": 2
                  },
                  "readOptional": true,
                  "description": "Language"
                }
              ]
            },
            "readOptional": true,
            "description": "Preferences"
          }
        ]
      },
      "primarySources": {
        "email": 1604839201
      },
      "resolveIdentitiesOnBatchImport": false,
      "identifiers": [
        "customerId",
        "email"
      ],
      "mode": "Normal",
      "uiPreferences": {
        "userProfile": {
          "firstName": "first_name",
          "lastName": "last_name",
          "extra": "email"
        }
      }
    }
  ]
}

Get workspace

Returns the current workspace.

The current workspace is the workspace associated with the API key (if it is a restricted key) or the one specified via the Krenalis-Workspace header. For more details, see the authentication documentation.

Request

No parameters.

Response

  • id

    int

    The ID of the workspace.

  • name

    string

    The workspace's name.

    It is not longer than 100 characters.

  • profileSchema

    schema

    The profile schema, defining the structure and properties of a profile of the workspace.

  • primarySources

    object with int values

    The primary source for each profile schema property that has one, where the key is the property name and the value is the connection identifier.

    This source defines where the definitive value for the property is read from, preventing other sources from overwriting it once it is set.

  • resolveIdentitiesOnBatchImport

    boolean

    Indicates whether identity resolution should be performed immediately after a batch import.

    If set to true, Krenalis will automatically resolve identities as soon as the import is finished. If set to false, identity resolution will not happen automatically and will need to be triggered separately.

  • identifiers

    array of string

    The profile schema properties used to determine if two users are the same. The identity resolution checks these identities in order. Two users are considered the same if they have the same value for the first identity, or if neither user has a value for the first identity, the identity resolution moves to the next one, and so on.

    If no identifiers are specified, once identity resolution is performed, all users will be considered different from each other.

  • mode

    string

    The mode of the data warehouse. If not specified, the default is "Normal".

    Possible values: "Normal", "Inspection" or "Maintenance".

  • uiPreferences

    object

    • uiPreferences.userProfile

      object

      • uiPreferences.userProfile.image

        string

        The path of the property in the profile schema that represents the user's image, in base64 format.

        It is not longer than 100 characters.

      • uiPreferences.userProfile.firstName

        string

        The path of the property in the profile schema to display as the first name in the profile header.

        It is not longer than 100 characters.

      • uiPreferences.userProfile.lastName

        string

        The path of the property in the profile schema for the user's last name.

        It is not longer than 100 characters.

      • uiPreferences.userProfile.extra

        string

        The path of the property in the profile schema for additional user information. For example, the profile schema property that represents the email.

        It is not longer than 100 characters.
GET /v1/workspaces/current
curl https://example.com/v1/workspaces/current \
-H "Authorization: Bearer api_xxxxxxx"
Response
{
  "id": 1371036433,
  "name": "Customers",
  "profileSchema": {
    "kind": "object",
    "properties": [
      {
        "name": "customer_id",
        "type": {
          "kind": "string",
          "maxLength": 36
        },
        "readOptional": true,
        "description": "Customer ID"
      },
      {
        "name": "first_name",
        "type": {
          "kind": "string",
          "maxLength": 100
        },
        "readOptional": true,
        "description": "First name"
      },
      {
        "name": "last_name",
        "type": {
          "kind": "string",
          "maxLength": 100
        },
        "readOptional": true,
        "description": "Last name"
      },
      {
        "name": "email",
        "type": {
          "kind": "string",
          "maxLength": 254
        },
        "readOptional": true,
        "description": "Email"
      },
      {
        "name": "phone_number",
        "type": {
          "kind": "string",
          "maxLength": 20
        },
        "readOptional": true,
        "description": "Phone number"
      },
      {
        "name": "birth_date",
        "type": {
          "kind": "date"
        },
        "readOptional": true,
        "description": "Birth date"
      },
      {
        "name": "gender",
        "type": {
          "kind": "string"
        },
        "readOptional": true,
        "description": "Gender"
      },
      {
        "name": "address",
        "type": {
          "kind": "object",
          "properties": [
            {
              "name": "street",
              "type": {
                "kind": "string",
                "maxLength": 255
              },
              "readOptional": true,
              "description": "Street"
            },
            {
              "name": "city",
              "type": {
                "kind": "string",
                "maxLength": 100
              },
              "readOptional": true,
              "description": "City"
            },
            {
              "name": "postal_code",
              "type": {
                "kind": "string",
                "maxLength": 20
              },
              "readOptional": true,
              "description": "Postal code"
            },
            {
              "name": "country",
              "type": {
                "kind": "string",
                "maxLength": 2
              },
              "readOptional": true,
              "description": "Country"
            }
          ]
        },
        "readOptional": true,
        "description": "Address"
      },
      {
        "name": "preferences",
        "type": {
          "kind": "object",
          "properties": [
            {
              "name": "newsletter",
              "type": {
                "kind": "boolean"
              },
              "readOptional": true,
              "description": "Newsletter subscription"
            },
            {
              "name": "categories",
              "type": {
                "kind": "array",
                "elementType": {
                  "kind": "string"
                }
              },
              "readOptional": true,
              "description": "Preferences categories"
            },
            {
              "name": "language",
              "type": {
                "kind": "string",
                "maxLength": 2
              },
              "readOptional": true,
              "description": "Language"
            }
          ]
        },
        "readOptional": true,
        "description": "Preferences"
      }
    ]
  },
  "primarySources": {
    "email": 1604839201
  },
  "resolveIdentitiesOnBatchImport": false,
  "identifiers": [
    "customerId",
    "email"
  ],
  "mode": "Normal",
  "uiPreferences": {
    "userProfile": {
      "firstName": "first_name",
      "lastName": "last_name",
      "extra": "email"
    }
  }
}
Errors
404
workspace does not exist

Delete the workspace

Deletes the current workspace.

The current workspace is the workspace associated with the API key (if it is a restricted key) or the one specified via the Krenalis-Workspace header. For more details, see the authentication documentation.

Request

No parameters.

Response

No response.
DELETE /v1/workspaces/current
curl -X DELETE https://example.com/v1/workspaces/current \
-H "Authorization: Bearer api_xxxxxxx"
Errors
404
workspace does not exist