Create project

Time	Status	User Agent
Retrieving recent requests…

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., Europe/London, America/Los_Angeles). Non-IANA or unsupported zones are rejected.

Request

{
  "orgId": 1,
  "displayName": "Sales Analytics",
  "language": "EN",
  "timezone": "Europe/London"
}

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": "Europe/London"
  },
  "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": "Europe/London",
  "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": "Europe/London",
  "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.

Handling Partial Successes

Basic Usage

Create with Connection Test

Create with Metadata (MDL)

Create with MDL, Instructions, and SQL Pairs

Database connectionInfo examples

201Successfully created project

207Project created with partial resource failures

400Bad request

401Unauthorized

403Forbidden - Org access denied