Import data with the REST API

Keatext has a REST API that allows you to create and update datasets programmatically (in other words, without going through the user interface or using a connector). Currently, there is no way to create projects directly with our REST API; you'll have to use the user interface.

Authentication

Authentication is done using basic_auth with the email and password associated to your Keatext account.

Create a dataset

You have to create a dataset before you populate it with data by sending a POST request to:

https://app.keatext.ai/api/v1/datasets

POST https://app.keatext.ai/api/v1/datasets/
Authorization: Basic ZW1haWxAZXhhbXBsZS5jb206cGFzc3dvcmQ=
Content-Type: application/json

{
    "name": "Listing reviews 2012-2014",
    "description": "All listing reviews in English between 2012 and 2014",
    "fields": [{
        "dataType": "Number",
        "analyze": false,
        "name": "review_id",
        "isPrimaryKey": true
    }, {
        "dataType": "Date",
        "analyze": false,
        "name": "review_date",
        "dateFormat": "MM-DD-YYYY"
    }, {
        "dataType": "String",
        "analyze": true,
        "name": "review_content"
    }]
}

curl -u your_email_address -H "Content-Type: application/json" -XPOST -d @request.json \
        https://app.keatext.ai/api/v1/datasets
Property Type Required Description
name string yes A name displayed in the user interface.
description string no A description displayed under the dataset's name in the dataset grid.
fields array yes
Property Type Required Description
dataType string yes The data type, either String, Number, Date or Boolean.
analyze boolean no Set to true if the content has the type String and must be analyzed.
name string yes The name of the field.
dateFormat string no The date format used if dataType is Date.
isPrimaryKey boolean no Set to true if the field value is a unique identifier. A dataset can only have one primary key.

If your request is well-formed, the response is a string id assigned to the newly created dataset. You'll need this id to populate your dataset or update the data it already contains.

{ "id": "5703d9432327d444004e7c3d" }
Header Type Description
X-RateLimit-Limit integer The number of requests allowed in the current period.
X-RateLimit-Reset integer The date and time the current period expires (UNIX timestamp).
X-RateLimit-Remaining integer The number of requests remaining in the current period.

These headers are included in every response from Keatext, whether the request tries to create, populate or update a dataset.

Populate a dataset

Data is added to a dataset by sending a POST request to:

https://app.keatext.ai/api/v1/datasets/{id}/records

where {id} is the id of the dataset to populate.

Try to limit each request to 100 records or so; a request will be rejected if it's too large. The last request should have the property hasMore set to false and all preceding requests should have it set to true.

POST https://app.keatext.ai/api/v1/datasets/{id}/records
Authorization: Basic ZW1haWxAZXhhbXBsZS5jb206cGFzc3dvcmQ=
Content-Type: application/json

{
    "records": [{
        "review_content": "Very nice and aesthetically pleasing accommodation.",
        "review_date": "10-06-2012",
        "review_id": "4055629"
    }, {
        "review_content": "It was great for the price and the description accurate.",
        "review_date": "05-08-2012",
        "review_id": "41133812"
    }],
    "hasMore": false
}

curl -u your_email_address -H "Content-Type: application/json" -XPOST -d @request.json \
        https://app.keatext.ai/api/v1/datasets/{id}/records
Property Type Required Description
records array yes A list of records with their metadata. Properties must be one of the fields defined previously.
hasMore boolean yes Set to false if pushing your last records. Triggers post-processing.

The response tells you how many records were received (totalProcessed), and how many were successfully processed (processed) or weren't (failed).

{ "processed": 2, "failed": 0, "totalProcessed": 2 }

Update a dataset

You can update a dataset by sending a PUT request to:

https://app.keatext.ai/api/v1/datasets/{id}/records

where {id} is the id of the dataset to update.

The request format is exactly the same as when you first populate the dataset. If your dataset has a primary key (set with the property isPrimaryKey when creating the dataset), previous records are updated if a primary key already exists. If the primary key doesn't exist, then a new record is created.

You cannot use a PUT request to update your dataset if the dataset has no primary field.

curl -u your_email_address -H "Content-Type: application/json" -XPUT -d @request.json \
        https://app.keatext.ai/api/v1/datasets/{id}/records

The response tells you how many records were updated (updatedText for analyzed fields and updatedMetadata for other fields), how many were created (created) and how many couldn't be processed (failed).

{ "updatedText": 0, "updatedMetadata": 2, "created": 0, "failed": 0 }

Delete a dataset

You can delete a dataset by sending a DELETE request to:

https://app.keatext.ai/api/v1/datasets/{id}

where {id} is the id of the dataset to delete.

curl -u your_email_address -XDELETE https://app.keatext.ai/api/v1/datasets/{id}

The response is a 204 No Content status code if the dataset is deleted successfully.

results matching ""

    No results matching ""