Overview

You can add a new Record to a Table in natural language with the Create Record with prompt endpoint.

You need to define several parameters to build the request for that endpoint.

These parameters are:

teamSlug, databaseId and tableSlug as well as API Key.
The prompt and autoInsert body parameters.

This guide will focus on explaining how to the define and use the prompt and autoInsert body parameters.

📘
The steps to obtain teamSlug, databaseId and tableSlug as well as the API Key are detailed in the Quickstart.

Prompt requirements

🚧
Mind the prompt
The prompt must meet the following requirements:

Include the names of the Fields in your Table

Have a value for each of the Fields

Each value must match the data type of the Field

autoInsert

The purpose of the autoInsert parameter is to give you the opportunity to check the response and possibly amend it before actually adding the new Record to the Table.

The autoInsert is a boolean:

When set to false in your request, Morph API will return the executed SQL, the record to insert in the Table as an object and an error, without actually adding the record to the Table. This is your opportunity to check or amend your request. It acts as a kind of preview if you will.
When set to true, the record will be added to the Table as per the response you will receive with the executed SQL, the record object to be inserted. Unless there is an error in the process

By default autoInsert is set to false (boolean). As an optional parameter, autoInsert can omitted in the request. In which case, its value will automatically be set to its default value, false.

Example for this guide

We will take the sample CRM table from Create Record with prompt in the API reference, to see how to use and define prompt and autoInsert body parameters.

To demonstrate the purpose of the autoInsert body parameter, we will add the Record in two steps:

Step 1: Request to add a Record with prompt without inserting the value in the Table. By omitting the autoInsert parameter in the request (equivalent to explicitly setting its value to false).
Step 2: request to effectively insert the Record in the Table by setting autoInsert to true.

👍
The step 1 is optional.
You could send the request with autoInsert to true from the first request. In other words, skip step 1 and directly do step 2.

Setup to follow along

📘
Try myself
If you wish to follow this tutorial by trying the exact steps and and using the same sample CRM Table:

Create a new Table via CSV import. The steps to reproduce the same CSV file are described below.

In the CSV import screen, name your Table CSV Example. This way the tableSlug for this Table will be crm_example, exactly like in the cURL snippets provided further below.

How to create the exact same CSV file for the sample CRM Table:

Open a plain text editor. You can use a built-in text editor or a code editor like Visual Studio Code, Sublime Text, or any other text editor you prefer.
Create a new document in the text editor.
Copy all the data (including headers) from the code snippet below:

company_name,budget,deal_date
ABC Inc.,50000,2023-01-15
XYZ Corp,75000,2023-02-20
Acme Industries,60000,2023-03-10
Global Tech,80000,2023-04-05
Innovate Solutions,45000,2023-05-18
Smith & Co.,70000,2023-06-22
Johnson Enterprises,55000,2023-07-09
Widget World,90000,2023-08-14
Superior Systems,65000,2023-09-27
Peak Performance,85000,2023-10-30
Evergreen Holdings,52000,2023-11-25
Pioneer Partners,72000,2023-12-12
Golden Gate Group,48000,2024-01-08
Blue Sky Inc.,95000,2024-02-17
Star Solutions,60000,2024-03-21

Paste the copied data into the new document.
Save the document with a .csv extension. To do this, click on "File" in the menu bar, then select "Save As."
In the "Save As" dialog, choose the location where you want to save the CSV file.
In the "Save As" dialog, provide a name for the file followed by the .csv extension. For example, you can name it "CRM Example.csv."
In the "Encoding" dropdown, select "UTF-8" or "Unicode (UTF-8)" to ensure proper character encoding.
Click the "Save" button to save the file.

Your data is now saved in a CSV file with the specified name and extension.

You can view it in Morph and in the Developer Mode.

In Morph:

In the Developer Mode:

Step 1: Record creation request

Let's look at a simple example of requesting to add a Record in natural language without requesting to insert the Record in the Table.

We will make an API request to the Create Record with prompt endpoint.

Taking the sample CRM Table from that API reference. That Table has the fields company_name, budget and deal_date:


Column name	`company_name`	`budget`	`deal_date`
Data type	`Short Text`	`Number`	`Date`

Build the request

To build the request, you will need the following parameters.

Headers

authorization header: x-api-key: {YOUR_API_KEY}
client-type: widget
Content-Type: application/json

ℹ️
How to get my API Key?
Head to Create an API Key.

Path parameters

teamSlug
databaseId
tableSlug

ℹ️
Where can I find my teamSlug, databaseId and tableSlug?
Go to How to find teamSlug, databaseId and tableSlug.

Body parameter

We will need to define:

prompt parameter: write your input natural language the values for each Field in that Table, with the matching data types (cf. Prompt requirements).
Set autoInsert to false. Two equivalent ways to do it. Omit the autoInsert parameter, or explicitly set its value to false.

Here is a prompt template where autoInsert is omitted:

{
  "prompt": "{INPUT IN NATURAL LANGUAGE WITH VALUES FOR EACH FIELD OF THE TABLE WITH MATCHING DATA TYPES}"
}

Which is equivalent to this prompt template where autoInsert is added and its value explicitly set to false:

{
  "prompt": "{INPUT IN NATURAL LANGUAGE WITH VALUES FOR EACH FIELD OF THE TABLE WITH MATCHING DATA TYPES}",
  "autoInsert": false
}

For our CRM Table example.

A valid prompt example where autoInsert is omitted:

{
  "prompt": "I talked with Morph, Inc. They said their budget is $1M at most. This meeting was held in 2021/02/01"
}

Which is equivalent to this prompt example where autoInsert is added and its value explicitly set to false:

{
  "prompt": "I talked with Morph, Inc. They said their budget is $1M at most. This meeting was held in 2021/02/01",
  "autoInsert": false
}

Make the API request

cURL

To make the HTTP request directly using cURL:

Open a Terminal window.
Replace the following placeholders in the cURL template below with your own values.
- In the URL:
  - {YOUR_TEAM_SLUG}
  - {YOUR_DATABASE_ID}
  - {YOUR_TABLE_SLUG}
- In the headers:
  - {YOUR_API_KEY} for the x-api-key
Run the command in your Terminal.

Replace the placeholders with your own values.

Template where autoInsert is omitted:

curl --X POST 'https://{YOUR_TEAM_SLUG}.api.morphdb.io/v0/record/{YOUR_DATABASE_ID}/{YOUR_TABLE_SLUG}/create/prompt' \
--header 'Content-Type: application/json' \
--header 'client-type: widget' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
  "prompt": "{INPUT IN NATURAL LANGUAGE WITH VALUES FOR EACH FIELD OF THE TABLE WITH MATCHING DATA TYPES}"
}'

Template where autoInsert is added and its value explicitly set to false:

curl --X POST 'https://{YOUR_TEAM_SLUG}.api.morphdb.io/v0/record/{YOUR_DATABASE_ID}/{YOUR_TABLE_SLUG}/create/prompt' \
--header 'Content-Type: application/json' \
--header 'client-type: widget' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
  "prompt": "{INPUT IN NATURAL LANGUAGE WITH VALUES FOR EACH FIELD OF THE TABLE WITH MATCHING DATA TYPES}",
  "autoInsert": false
}'

With values for our CRM Table example.

A valid prompt example where autoInsert is omitted:

curl --X POST 'https://acme.api.morphdb.io/v0/record/dw5g1h89-2637-253k-452b-7803j4x7e3vi/crm_example/create/prompt' \
--header 'Content-Type: application/json' \
--header 'client-type: widget' \
--header 'x-api-key: ms5sCDEOVNuIw92MNA3qLKih4xzY25D9PQY6D7Az2' \
--data '{
  "prompt": "I talked with Morph, Inc. They said their budget is $1M at most. This meeting was held in 2021/02/01"
}'

curl --X POST 'https://acme.api.morphdb.io/v0/record/dw5g1h89-2637-253k-452b-7803j4x7e3vi/crm_example/create/prompt' \
--header 'Content-Type: application/json' \
--header 'client-type: widget' \
--header 'x-api-key: ms5sCDEOVNuIw92MNA3qLKih4xzY25D9PQY6D7Az2' \
--data '{
  "prompt": "I talked with Morph, Inc. They said their budget is $1M at most. This meeting was held in 2021/02/01",
  "autoInsert": false
}'

Response

A successful response will return the executed SQL, the record to insert in the Table as an object and an error properties, without actually adding the record to the Table. This is your opportunity to check or amend your request.

🚧
Record not added
Notice that this record has NOT been added to the Table. This is because we set autoInsert to false (or omitted it) in the request.

You should see the following successful response in your Terminal:

{
  "sqls": [
    "insert into \"crm_example\" (\"budget\", \"company_name\", \"deal_date\", \"id\") values (1000000, 'Morph, Inc.', '2021-02-01', 1)"
  ],
  "records": [
    {
      "tableSlug": "crm_example",
      "record": {
        "id": 1,
        "company_name": "Morph, Inc.",
        "budget": 1000000,
        "deal_date": "2021-02-01"
      }
    }
  ],
  "error": null
}

Debugging

📘
Not the expected result?
Try the following debugging steps.

Step 2: Record insertion

In this step, you will actually add a Record in the Table. Regardless if you chose to follow step 1 first or to jump straight away into this step 2.

Build the request

To build the request, you will need the following parameters. The Headers and Path parameters are the same than in Step 1. Only the body parameters will change.

Headers

authorization header: x-api-key: {YOUR_API_KEY}
client-type: widget
Content-Type: application/json

ℹ️
How to get my API Key?
Head to Create an API Key.

Path parameters

teamSlug
databaseId
tableSlug

ℹ️
Where can I find my teamSlug, databaseId and tableSlug?
Go to How to find teamSlug, databaseId and tableSlug.

Body parameter

We will need to define:

prompt parameter: write your input natural language the values for each Field in that Table, with the matching data types (cf. Prompt requirements).
Set autoInsert to true. You need to explicitly add it and set its value to true. If you omit the autoInsert parameter, its value will automatically be set to false.

Here is a prompt template with autoInsert explicitly set to true:

{
  "prompt": "{INPUT IN NATURAL LANGUAGE WITH VALUES FOR EACH FIELD OF THE TABLE WITH MATCHING DATA TYPES}",
  "autoInsert": true
}

For our CRM Table example.

A valid prompt example with autoInsert explicitly set to true:

{
  "prompt": "I talked with Morph, Inc. They said their budget is $1M at most. This meeting was held in 2021/02/01",
  "autoInsert": true
}

Make the API request

cURL

To make the HTTP request directly using cURL:

Open a Terminal window.
Replace the following placeholders in the cURL template below with your own values.
- In the URL:
  - {YOUR_TEAM_SLUG}
  - {YOUR_DATABASE_ID}
  - {YOUR_TABLE_SLUG}
- In the headers:
  - {YOUR_API_KEY} for the x-api-key
Run the command in your Terminal.

Replace the placeholders with your own values.

Template where autoInsert is added and its value explicitly set to true:

curl --X POST 'https://{YOUR_TEAM_SLUG}.api.morphdb.io/v0/record/{YOUR_DATABASE_ID}/{YOUR_TABLE_SLUG}/create/prompt' \
--header 'Content-Type: application/json' \
--header 'client-type: widget' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
  "prompt": "{INPUT IN NATURAL LANGUAGE WITH VALUES FOR EACH FIELD OF THE TABLE WITH MATCHING DATA TYPES}",
  "autoInsert": true
}'

With values for our CRM Table example.

A valid prompt example where autoInsert is omitted:

curl --X POST 'https://acme.api.morphdb.io/v0/record/dw5g1h89-2637-253k-452b-7803j4x7e3vi/crm_example/create/prompt' \
--header 'Content-Type: application/json' \
--header 'client-type: widget' \
--header 'x-api-key: ms5sCDEOVNuIw92MNA3qLKih4xzY25D9PQY6D7Az2' \
--data '{
  "prompt": "I talked with Morph, Inc. They said their budget is $1M at most. This meeting was held in 2021/02/01",
  "autoInsert": true
}'

Response

A successful response will return the executed SQL, the record to insert in the Table as an object and an error properties, AND actually adding the record to the Table. This is your opportunity to check or amend your request.

👍
Added
This time the record has been added to the Table. This is because we set autoInsert to false (or omitted it) in the request.

You should see the following successful response in your Terminal:

{
  "sqls": [
    "insert into \"crm_example\" (\"budget\", \"company_name\", \"deal_date\", \"id\") values (1000000, 'Morph, Inc.', '2021-02-01', 1)"
  ],
  "records": [
    {
      "tableSlug": "crm_example",
      "record": {
        "id": 1,
        "company_name": "Morph, Inc.",
        "budget": 1000000,
        "deal_date": "2021-02-01"
      }
    }
  ],
  "error": null
}

In Morph and Developer Mode

You can view it in Morph and in the Developer Mode.

In Morph:

in the Developer Mode:

Debugging

📘
Not the expected result?
Try the following debugging steps.