Profile schema

Endpoints for reading and modifying the workspace's profile schema.

Get schema

Returns the profile schema of the workspace.

Request

No parameters.

Response

GET /v1/profiles/schema
curl https://example.com/v1/profiles/schema \
-H "Authorization: Bearer api_xxxxxxx"
Response
{
  "schema": {
    "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"
      }
    ]
  }
}
Errors
404
workspace does not exist

Alter schema

Alters the profile schema of the workspace.

Request

  • schema

    schema Required

    The new profile schema. It must define at least one property.

    Property names cannot begin with an underscore, as Krenalis reserves leading underscores for system-managed columns in the profiles view, such as _kpid and _updated_at.

  • primarySources

    object with int values

    The primary source for each 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.

    If no primary source is provided, the new schema will have no primary sources defined.

  • rePaths

    object with string values

    Specifies renamed properties and additional information that cannot be expressed through the schema parameter alone.

    In particular:

    • If a property in schema has been renamed, the new path must be added as a key in rePaths and the old path as the associated value. Otherwise, instead of performing a rename operation, a new property with the new path would be created, and the property with the old path would be deleted.
    • If a property in schema has been added with the same path of an already existent one which should be removed, then the path of the new property must be added as a key in rePaths and null as the associated value. Otherwise, instead of creating a new property and deleting the old one, it would be interpreted as a rename operation.

Response

No response.
PUT /v1/profiles/schema
curl -X PUT https://example.com/v1/profiles/schema \
-H "Authorization: Bearer api_xxxxxxx" \
--json '{
"schema": {
"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": 1371036433
},
"rePaths": {
"street3": null
}
}'
Errors
404
workspace does not exist
422
primary source does not exist
422
data warehouse is in inspection mode
422
cannot alter the schema as specified
422
another operation is already executing

Preview alter schema

Returns the SQL queries that would be executed on the warehouse to alter the current profile schema to the specified one.

Calling this method has no side effects and does not make any changes to the schema.

Request

  • schema

    schema Required

    The new profile schema. It must define at least one property.

    Property names cannot begin with an underscore, as Krenalis reserves leading underscores for system-managed columns in the profiles view, such as _kpid and _updated_at.

  • rePaths

    object with string values

    Specifies renamed properties and additional information that cannot be expressed through the schema parameter alone.

    In particular:

    • If a property in schema has been renamed, the new path must be added as a key in rePaths and the old path as the associated value. Otherwise, instead of performing a rename operation, a new property with the new path would be created, and the property with the old path would be deleted.
    • If a property in schema has been added with the same path of an already existent one which should be removed, then the path of the new property must be added as a key in rePaths and null as the associated value. Otherwise, instead of creating a new property and deleting the old one, it would be interpreted as a rename operation.

Response

  • queries

    array of string

    The SQL queries that would be executed on the warehouse to alter the profile schema.
PUT /v1/profiles/schema/preview
curl -X PUT https://example.com/v1/profiles/schema/preview \
-H "Authorization: Bearer api_xxxxxxx" \
--json '{
"schema": {
"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"
}
]
},
"rePaths": {
"street3": null
}
}'
Response
{
  "queries": [
    "ALTER TABLE ..."
  ]
}
Errors
404
workspace does not exist
422
cannot alter the schema as specified

Get latest alter schema info

Returns information about the latest alter schema.

Depending on the returned values:

  • If neither startTime nor endTime are returned, it means that no alteration of the profile schema has ever been performed for the workspace.
  • If only startTime is returned, it means that the workspace is currently running a profile schema alteration.
  • If both startTime and endTime are returned, it means that a profile schema alteration has been performed and no profile schema alteration is currently running.

Request

No parameters.

Response

  • startTime

    nullable datetime

    Start timestamp (UTC) of the latest profile schema update, either running or completed.

    If null, no profile schema update has ever been started for the workspace.

  • endTime

    nullable datetime

    End timestamp (UTC) for the latest profile schema update.

    If null, it means that the profile schema update is still in progress, or that no schema update has ever been performed for the workspace.

  • error

    nullable string

    A possible error in the execution of the latest update of the profile schema.

    If null, it means that no update of the profile schema has ever been executed, or that one is in progress, or that the last one executed completed without errors.
GET /v1/profiles/schema/latest-alter
curl https://example.com/v1/profiles/schema/latest-alter \
-H "Authorization: Bearer api_xxxxxxx"
Response
{
  "startTime": "2025-01-12T09:37:22",
  "endTime": "2025-01-12T09:37:25",
  "error": null
}
Errors
404
workspace does not exist