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.

The project mode is chosen with projectType: omit it (or send CLASSIC) for a classic project, or send AGENTIC for an agent-mode project. See Create an agentic project below for what changes in agent mode.

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.

Who May Create a Project

Creating a project through the API clears the same gates as creating one in the app, so an organization cannot use the API to get around its plan:

Subscription — an organization whose subscription is neither active nor trialing gets 403 with code UNSUBSCRIBED_ACCESS.
Project ceiling — an organization that has reached its plan's project limit gets 403 with code PLAN_LIMIT_REACHED. The Free plan allows two projects.

Neither refusal creates anything.

{
  "id": "9a3d1c07-52be-4f18-8f2b-6d0e5a94c7b1",
  "code": "PLAN_LIMIT_REACHED",
  "error": "Free plan limit reached: 2 projects maximum. Upgrade to create more projects"
}

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.
projectType: CLASSIC (default) or AGENTIC. Any other value is rejected with a 400.

Request

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

Response

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

creditAward is part of every create response. It only ever carries a value for an agentic project — see Create an agentic project.

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",
    "projectType": "CLASSIC",
    "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",
  "creditAward": null
}

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", "isDefault": 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"
}

⚠️
isDefault, not isGlobal
A global instruction is flagged with isDefault: true on this endpoint. The Instructions API spells the same flag isGlobal; that spelling is ignored here, and an instruction sent with it is seeded as a non-global one.

Create an Agentic Project

Send projectType: "AGENTIC" to create an agent-mode project. Wren provisions the project's Git repositories before anything else, and everything the project models or knows lives there from then on.

What differs from a classic create:

MDL is committed, not just stored. A supplied mdl is persisted, committed to the project's shared-data repository, and deployed — the same path the modeling UI takes. The response adds commitSha, the commit that carries the manifest.
sqlPairs and instructions are rejected with a 400. Agent-mode knowledge is files; commit it through the Files API once the project exists.
A data source stays optional. You can create the project first and attach type/connectionInfo later with PUT /v2/projects/{projectId}.
Repository provisioning is fatal. If Wren cannot initialize the project's repositories the call returns 500 and the half-created project is removed, so a failed create leaves nothing behind.
The first agentic project may earn credits. An organization on an active paid plan receives a one-time Agentic Mode credit grant with its first agentic project, reported as creditAward. It is null once redeemed, and for organizations that are not eligible. The grant is best-effort — if it fails, the project is still created and creditAward comes back null.

Request

{
  "orgId": 1,
  "displayName": "Revenue Agent",
  "language": "EN",
  "timezone": "Europe/London",
  "projectType": "AGENTIC",
  "mdl": {
    "models": [
      {
        "name": "orders",
        "columns": [
          { "name": "order_id", "type": "VARCHAR", "notNull": true },
          { "name": "amount", "type": "DOUBLE" }
        ],
        "primaryKey": "order_id",
        "tableReference": { "catalog": "memory", "schema": "main", "table": "orders" }
      }
    ],
    "relationships": [],
    "views": []
  }
}

Response

{
  "project": {
    "id": 125,
    "type": null,
    "projectType": "AGENTIC",
    "displayName": "Revenue Agent",
    "createdAt": "2025-09-11T12:45:00Z",
    "updatedAt": "2025-09-11T12:45:00Z",
    "connectionInfo": null,
    "language": "EN",
    "timezone": "Europe/London"
  },
  "status": "succeeded",
  "commitSha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
  "creditAward": { "amount": 500, "plan": "ESSENTIAL" }
}

{
  "id": "5b1f7a92-3c64-4f0d-9b8e-2a7c6d1e4f30",
  "error": "sqlPairs/instructions are not supported for agent-mode projects. Commit knowledge files via /api/v2/projects/{id}/files instead."
}

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

Who May Create a Project

Basic Usage

Create with Connection Test

Create with Metadata (MDL)

Create with MDL, Instructions, and SQL Pairs

Create an Agentic Project

Database connectionInfo examples

201Project created

207Project created with partial resource setup

400Missing/invalid fields, or connection test failure. Also returned when projectType is neither CLASSIC nor AGENTIC, or when an AGENTIC create carries sqlPairs or instructions.

401Unauthorized: invalid or missing org API key.

403The organization may not create another project. code is UNSUBSCRIBED_ACCESS when its subscription is neither active nor trialing, or PLAN_LIMIT_REACHED when its plan's project ceiling is reached (the Free plan allows two). Nothing is created either way.

405Method not allowed.

500Internal server error. An AGENTIC create also fails here when the deployment has no Git server configured, or when provisioning the project's repositories fails (the project row is rolled back).