Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.maia.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Project Provisioning API provides a set of flexible, modular endpoints to allow the programmatic creation of a project within . 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 interface.
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 supported data warehouses are SNOWFLAKE and REDSHIFT, with a deployment type of HYBRID or FULL_SAAS. Future updates will add support for other warehouses.

​
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 supported warehouse and authentication combinations are:
WarehouseAuthentication Type
Snowflakekey_pair
Amazon Redshiftpassword
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. Example request body: 
{
    "name": "my-warehouse-connection",
    "platformConnectionType": "dwh",
    "authProvider": "snowflake",
    "authType": "key_pair"
}
Example success response: 
HTTP 201 Created

{}

​
Create Secret - Full SaaS only

If using a Full SaaS , you will need to create a secret containing the warehouse connection credentials for your chosen warehouse type. This request will securely store the provided credentials into the Matillion-hosted vault, and allow you to reference them when creating an environment.

​
Request Structure

There are a handful of fields to provide as part of the request: name: The name of the secret that is to be created. This is how you will refer to the secret in any subsequent requests. type: The type of secret to be created. For data warehouse credentials, this should be set to DWH_PASSWORD. key: The key which contains the data warehouse credential within the secret value itself. value: The secret to be stored, such as a password or private key.
When providing a private key, the value MUST include \n newline characters to ensure that it is properly formatted. See example below.

​
Example request

Note the differing URL path for this request. The agentId can be fetched from the agents API endpoints. Base URL: POST /v1/secrets/{agentId}/secret-value Ensure that the {agentId} variable is replaced with the target agent ID that belongs to the project created in the initial request. Example request body: 
{
    "name": "snowflake-private-key",
    "type": "DWH_PASSWORD",
    "key": "password",
    "value": {
        "password": "-----BEGIN PRIVATE KEY-----\n.....\n-----END PRIVATE KEY-----"
    }
}
Example response: 
HTTP 201 Created
{
    "vaultSecretName": "snowflake-private-key",
    "resolver_ref": "${srs-mhcv:1:DWH_PASSWORD/snowflake-private-key@password}"
}

​
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 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).
Currently, the connection details for the warehouse connection are provided via the connectionOverrides block as detailed below. These overrides correspond to the connections defined here in defaultConnections. Each environment expects a separate data warehouse connection. If the same data warehouse connection is used across multiple environments, adding or modifying details in one environment will affect the others.
connectionOverrides: Allows you to provide details for the data warehouse connection.
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.

​
Snowflake

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

{}

​
Redshift

Example request body: 
{
    "name": "development",
    "displayName": "Development Only",
    "description": "An optional description",
    "defaultAgentId": "28d7eae0-1ed5-42d1-b2d9-67decbdef2c3",
    "defaultUserAccessLevel": "admin",
    "defaultConnections": {
        "DWH": {
            "redshift": "my-redshift-connection"
        }
    },
    "connectionOverrides": [
        {
            "connectionName": "my-redshift-connection",
            "connectionProperties": {
                "url": {
                    "value": "cluster.name.eu-west-1.redshift.amazonaws.com"
                },
                "username": {
                    "value": "redshift-username"
                },
                "port": {
                    "value": "5439"
                },
                "defaultDatabase": {
                    "value": "devDatabase"
                },
                "useSsl": {
                    "value": "true"
                },
                "defaultSchema": {
                    "value": "public"
                },
                "defaultStorageLocation": {
                    "value": "optional-default-storage-location"
                },
                "password": {
                    "secretName": "my-redshift-credentials",
                    "secretKey": "my-redshift-key"
                }
            }
        }
    ]
}
Example success response: 
HTTP 201 Created

{}

​
Initialize Repository

After creating the project, this endpoint allows a Git repository to be associated with the project. While 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.

​
Authentication

For GitHub repositories, uses GitHub App authentication to securely connect to your repository. This means you do not need to create or provide a Personal Access Token (PAT) — authentication is handled automatically.
The Git-Provider-Access-Token header is not required for GitHub.

​
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"
}

Request Body
{
  "provider": "github",
  "providerParameters": {
    "ownerName": "github-organization-name"
  },
  "repositoryName": "my-github-repository"
}
Example success response: 
HTTP 201 Created

{}