Create project

Create a new project and optionally wire up a database connection, import MDL (schema), seed instructions, and SQL pairs.

Handling Partial Successes

Successful requests that fully succeed return 201 Created.
If the project is created but some sub-steps fail, the API returns 207 Multi-Status and includes error details for the failed steps.
Sensitive fields in connectionInfo are redacted in responses (e.g. shown as ******).

📘
Explanation & Best Practices

Why 207?: The 207 Multi-Status code is appropriate when you want to indicate that part of a request succeeded and part failed—this aligns with its definition in the HTTP spec, particularly in WebDAV and similar contexts.

Redacting sensitive data: It’s standard security practice to mask or redact sensitive fields (like credentials or other private connection info) in API responses.

Basic Usage

Basic parameters

language: use WrenAILanguage codes (e.g., EN, ES, FR, ZH_TW, ZH_CN, DE, PT, RU, JA, KO, IT, FA_IR, AR, NL). Internally these map to human-readable names on UI.
timezone: use a valid IANA time zone name (e.g., UTC, America/Los_Angeles). Non-IANA or unsupported zones are rejected.

Request

{
  "orgId": 1,
  "displayName": "Sales Analytics",
  "language": "EN",
  "timezone": "UTC"
}

Response

{
  "project": {
    "id": 123,
    "type": "POSTGRES",
    "displayName": "Sales Analytics",
    "createdAt": "2025-09-11T12:34:56Z",
    "updatedAt": "2025-09-11T12:34:56Z",
    "connectionInfo": null,
    "language": "EN",
    "timezone": "UTC"
  },
  "status": "succeeded"
}

Create with Connection Test

Set type, provide connectionInfo, and set testConnection to preflight the credentials. If the test fails, you’ll get a 400; if success, normal creation proceeds.

Request (Postgres)

{
  "orgId": 1,
  "displayName": "Ops DWH",
  "language": "EN",
  "timezone": "America/Los_Angeles",
  "type": "POSTGRES",
  "connectionInfo": {
    "host": "db.internal",
    "port": 5432,
    "user": "app",
    "password": "s3cret",
    "database": "warehouse",
    "ssl": true
  },
  "testConnection": true
}

Response (redacted connectionInfo)

{
  "project": {
    "id": 124,
    "type": "POSTGRES",
    "displayName": "Ops DWH",
    "createdAt": "2025-09-11T12:40:00Z",
    "updatedAt": "2025-09-11T12:40:00Z",
    "connectionInfo": {
      "host": "db.internal",
      "port": 5432,
      "user": "app",
      "password": "******",
      "database": "warehouse",
      "ssl": true
    },
    "language": "EN",
    "timezone": "America/Los_Angeles"
  },
  "status": "succeeded"
}

Create with Metadata (MDL)

Provide an MDL manifest to import models (and best-effort relationships/views).

Request (minimal)

{
  "orgId": 1,
  "displayName": "Retail BI",
  "language": "EN",
  "timezone": "UTC",
  "mdl": {
    "models": [
      {
        "name": "customers",
        "columns": [
          { "name": "customer_id", "type": "VARCHAR", "notNull": true },
          { "name": "customer_city", "type": "VARCHAR" }
        ],
        "primaryKey": "customer_id",
        "tableReference": { "catalog": "memory", "schema": "main", "table": "customers" },
        "properties": { "displayName": "Customers" }
      }
    ],
    "relationships": [],
    "views": []
  }
}

Response (partial example if some best-effort steps fail)

{
  "project": { "...": "..." },
  "status": "partial",
  "errors": [
    { "resource": "views", "message": "View \"sales_by_city\" failed: question is required" }
  ]
}

Create with MDL, Instructions, and SQL Pairs

Seed instructions and SQL pairs at creation.

Request

{
  "orgId": 1,
  "displayName": "Growth Insights",
  "language": "EN",
  "timezone": "UTC",
  "mdl": {
    "models": [
      { "name": "orders", "columns": [{ "name": "order_id", "type": "VARCHAR", "notNull": true }], "primaryKey": "order_id" }
    ],
    "relationships": [],
    "views": []
  },
  "instructions": [
    { "instruction": "Always include order_id in order analysis", "isGlobal": true },
    { "instruction": "Aggregate by month when asked 'by month'", "questions": ["by month", "monthly"] }
  ],
  "sqlPairs": [
    { "question": "Top 10 customers by orders", "sql": "SELECT customer_id, COUNT(*) c FROM orders GROUP BY customer_id ORDER BY c DESC LIMIT 10" }
  ]
}

Response

{
  "project": { "...": "..." },
  "status": "succeeded"
}

Database connectionInfo examples

Use the type below and the corresponding connectionInfo shape. You can set "testConnection": true to validate prior to saving.

BIG_QUERY

{
  "type": "BIG_QUERY",
  "connectionInfo": {
    "projectId": "gcp-project",
    "datasetId": "analytics",
    "credentials": "{ \"type\": \"service_account\", \"client_email\": \"svc@...\", \"private_key\": \"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\" }",
    "sourceProjectId": "gcp-project-src",
    "sourceDatasetId": "raw"
  }
}

POSTGRES

{
  "type": "POSTGRES",
  "connectionInfo": {
    "host": "db.internal",
    "port": 5432,
    "user": "app",
    "password": "s3cret",
    "database": "warehouse",
    "ssl": true
  }
}

MYSQL

{
  "type": "MYSQL",
  "connectionInfo": {
    "host": "db.internal",
    "port": 3306,
    "user": "app",
    "password": "s3cret",
    "database": "warehouse",
    "ssl": true
  }
}

ORACLE

{
  "type": "ORACLE",
  "connectionInfo": {
    "user": "app",
    "password": "s3cret",
    "host": "oracle.internal",
    "port": 1521,
    "database": "ORCLCDB",
    "dsn": "oracle.internal:1521/ORCLCDB"
  }
}

MSSQL

{
  "type": "MSSQL",
  "connectionInfo": {
    "host": "mssql.internal",
    "port": 1433,
    "user": "app",
    "password": "s3cret",
    "database": "warehouse",
    "trustServerCertificate": true
  }
}

CLICK_HOUSE

{
  "type": "CLICK_HOUSE",
  "connectionInfo": {
    "host": "clickhouse.internal",
    "port": 8443,
    "user": "app",
    "password": "s3cret",
    "database": "analytics",
    "ssl": true
  }
}

TRINO

{
  "type": "TRINO",
  "connectionInfo": {
    "host": "trino.internal",
    "port": 443,
    "schemas": "hive.default,iceberg.analytics",
    "username": "app",
    "password": "s3cret",
    "ssl": true
  }
}

SNOWFLAKE (password auth)

{
  "type": "SNOWFLAKE",
  "connectionInfo": {
    "user": "APP",
    "account": "ACCT",
    "database": "ANALYTICS",
    "schema": "PUBLIC",
    "password": "s3cret",
    "warehouse": "COMPUTE_WH"
  }
}

SNOWFLAKE (private key auth)

{
  "type": "SNOWFLAKE",
  "connectionInfo": {
    "user": "APP",
    "account": "ACCT",
    "database": "ANALYTICS",
    "schema": "PUBLIC",
    "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
    "warehouse": "COMPUTE_WH"
  }
}

ATHENA

{
  "type": "ATHENA",
  "connectionInfo": {
    "database": "analytics",
    "schema": "public",
    "s3StagingDir": "s3://bucket/athena-results/",
    "awsRegion": "us-east-1",
    "awsAccessKey": "AKIA...",
    "awsSecretKey": "s3cret"
  }
}

REDSHIFT (password auth)

{
  "type": "REDSHIFT",
  "connectionInfo": {
    "host": "redshift-cluster.internal",
    "port": 5439,
    "user": "app",
    "password": "s3cret",
    "database": "dev",
    "redshiftType": "PASSWORD"
  }
}

REDSHIFT (IAM auth)

{
  "type": "REDSHIFT",
  "connectionInfo": {
    "clusterIdentifier": "rs-cluster",
    "user": "app",
    "database": "dev",
    "awsRegion": "us-east-1",
    "awsAccessKey": "AKIA...",
    "awsSecretKey": "s3cret",
    "redshiftType": "IAM"
  }
}

Notes

If testConnection is true, provide enough fields for a live connectivity check.