How to use the SQL generators via the public API

Integrate with our public API in no time and enable your users to get accurate SQL generations.

Table of contents

• Introduction
• Text-to-SQL generation

Introduction

To get started you need to:

• get your secret access token
• a subscription that include public API access

Text-to-SQL generation

Below you see how to do a text-to-SQL request that uses your custom data source (i.e. database schema) and translates the text input into a SQL query:

const response = await fetch('https://api.sqlai.ai/api/public/v2', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ACCESS_TOKEN`
  },
  body: JSON.stringify({
    prompt: 'Get user with id 13',
    engine: 'postgres',
    engineVersion: '17',
    mode: 'textToSQL',
    dataSource: [
      { "table": "actor", "column": "actor_id", "type": "smallint" },
      { "table": "actor", "column": "name", "type": "text" }
      // ...
    ]
  }),
});
const { query, error } = await response.json();
console.log(query); // SELECT * FROM users WHERE id = '13';

Options

• prompt: Text-to-SQL instructions
• engine: Target database engine See supported database engines (use the “Public API name”)
• engineVersion: Target database engine version (optional)
• dataSourceId: Include database schema already imported into SQLAI.ai. You can find the dataSourceId under your added datasources (optional)
• dataSource: Include database schema directly with request, see formats below (optional)

Datasource formats

You can add the dataSource in 2 different formats; as an array or string. We recommend formatting the database schema as an array as it ensures optimal formatting on our side and doesn’t restrict the size of the database schema so much. The database schema array has the following format:

[
  {
    "table": "users",
    "column": "id",
    "type": "number",
    "meta": "" // Optional, e.g., foreign key relations
  },
  {
    "table": "users",
    "column": "name",
    "type": "text",
  }
]

You can get your database schema as an array by running this SQL query.

If you have the opportunity to do this or if you database schema is really small, you can also include it as a string, e.g. a CSV formatted string table_name,column_name,type:

users,id,number
users,name,text

When using database schemas as string, the size is limited to roughly 30-50 tables depending on size.