API Reference

Create project

post
https://example.com/api/v2/projects

Creates a new project and optionally imports MDL, instructions, and SQL pairs

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

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.
Body Params
integer
required
string
required

Project name (trimmed, non-empty, max 50 chars).

string
string
string

Data source type. Required when connectionInfo is provided.

connectionInfo
object

Data source connection details.

mdl
object

MDL manifest.

sqlPairs
array of objects
sqlPairs
instructions
array of objects
instructions
string
boolean

If true (with connectionInfo), run a live connection test before creating.

Responses

Updated about 1 month ago

Did this page help you?
Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated about 1 month ago

Did this page help you?