Project Provisioning API

The Project Provisioning API provides a set of flexible, modular endpoints to allow the programmatic creation of a project within the Data Productivity Cloud.

Each API endpoint handles a subset of the information required to provision a project, and executing all of these endpoints as detailed below will result in a functional project that can be accessed through the Designer interface.

Note

It is important to bear in mind that, until the intended users of the project are manually invited, the project will only be visible/accessible by users with the Super Admin role.

---

Create project

This is the first endpoint to be called in the process, which initializes the project with minimal information. A successful request will produce a v4 UUID, which will be required for the subsequent endpoints.

Currently, the only supported data warehouse is SNOWFLAKE, with an agent deployment type of HYBRID. Future updates will add support for other warehouses, as well as Full SaaS agents.

Example request

Base URL: POST /v1/projects

Example request body:

{
  "name": "my-project-name",
  "description": "An optional description of the project.",
  "warehouse": "SNOWFLAKE",
  "agentDeploymentType": "HYBRID"
}

Example success response:

HTTP 201 Created
{
  "projectId": "678d39a9-98e2-45e7-80db-3e90d0942eaf"
}

---

Create Default Warehouse Connection

Adding a default warehouse connection sets up basic configuration for connecting to a data warehouse. Currently, the only supported warehouse is snowflake, with key_pair as the only authentication mechanism.

Note

This endpoint only defines basic metadata for the warehouse, not the actual credentials for connecting to the warehouse. These are provided in the Create Environment request below.

Example request

Base URL: POST /v1/projects/{projectId}/data-platform-connections

Ensure that the {projectId} variable is replaced with the target project ID from the initial request to create the project.

Only the name of the connection needs to be altered—the remaining parameters can be provided as per this example request body:

{
    "name": "my-warehouse-connection",
    "platformConnectionType": "dwh",
    "authProvider": "snowflake",
    "authType": "key_pair"
}

Example success response:

HTTP 201 Created

{}

---

Create Environment

Request Structure

When creating an environment, there are a number of fields to provide:

name The name of the environment. This is an immutable identifier for the environment, and is used in other requests to refer to this specific environment.

description (optional) An optional, text description for the environment.

defaultAgentId The UUID of the agent that will be used by default for this environment.

defaultUserAccessLevel The default access level that will be assigned to a user for the environment, when they are added to the project. The accepted values are one of:

• default
• admin
• runner
• readOnly
• noAccess

defaultConnections Specifies the default data warehouse connection for the environment. Ensure that the value provided here is identical to the name of the connection defined in the previous request (my-warehouse-connection).

connectionOverrides Allows you to provide details for the data warehouse connection.

Note

Within the connectionProperties, the passphrase is only required if the password itself is encrypted. For more information, see Storing the private key.

Example request

Base URL: POST /v1/projects/{projectId}/environments

Ensure that the {projectId} variable is replaced with the target project ID from the initial request to create the project.

Example request body:

{
    "name": "development",
    "displayName": "Development Only",
    "description": "An optional description",
    "defaultAgentId": "28d7eae0-1ed5-42d1-b2d9-67decbdef2c3",
    "defaultUserAccessLevel": "admin",
    "defaultConnections": {
        "DWH": {
            "snowflake": "my-warehouse-connection"
        }
    },
    "connectionOverrides": [
        {
            "connectionName": "my-warehouse-connection",
            "connectionProperties": {
                "account": {
                    "value": "snowflake.account-name"
                },
                "username": {
                    "value": "SNOWFLAKE_USERNAME"
                },
                "defaultRole": {
                    "value": "SNOWFLAKE_ROLE"
                },
                "defaultWarehouse": {
                    "value": "SNOWFLAKE_WAREHOUSE_NAME"
                },
                "defaultDatabase": {
                    "value": "SNOWFLAKE_DATABASE_NAME"
                },
                "defaultSchema": {
                    "value": "SNOWFLAKE_SCHEMA"
                },
                "privateKey": {
                    "secretName": "aws-secret-name-for-snowflake-private-key"
                },
                "passphrase": {
                    "secretName": "password-encryption-key-secret-name",
                    "secretKey": "snowflake-private-key-password"
                }
            }
        }
    ]
}

Example success response:

HTTP 201 Created

{}

---

Initialize Repository

After creating the project, this endpoint allows a Git repository to be associated with the project. Whilst the Data Productivity Cloud does support a number of different Git providers, only GitHub is currently supported through the Project Provisioning APIs. This also means that Full SaaS repositories are not currently supported.

Before calling this endpoint, you need to create a Personal Access Token (PAT), which is a required request header. The key for the request header is Git-Provider-Access-Token.

Warning

As per the recommendation of GitHub, only "fine-grained" Personal Access Tokens will be accepted as part of this request. "Classic" tokens will be explicitly rejected, regardless of scopes.

Example request

Base URL: POST /v1/projects/{projectId}/repositories

Ensure that the {projectId} variable is replaced with the target project ID from the initial request to create the project.

Example request parameters:

Request Headers
{
  "Authorization": "Bearer ey.abc.jwt",
  "Git-Provider-Access-Token": "github_pat_11ABC123..."
}

Request Body
{
  "provider": "github",
  "providerParameters": {
    "ownerName": "github-organization-name"
  },
  "repositoryName": "my-github-repository"
}

Example success response:

HTTP 201 Created

{}