Get our latest book on "Top 10 artificial intelligence myths."
Download

Last updated

March 4, 2021

Table of contents

Impira Read/Write API

This guide walks through how to use Impira’s API. You can use the API to upload files, write data, update fields, and run IQL queries against data in Impira. We strive to offer every function in the UI through our API so you can mix and match the right combination of UI and API for your use. This guide is divided into multiple sections to walk you through each core feature of the API.

Find your Org name

Your Org name will appear in the API end-point used to query your data. To find your Org name, look in the browser URL bar. Your org name appears in the URL path after the ‘/o/’ subdirectory.

``` language="bash"
https://app.impira.com/o/<YOUR_ORG_NAME>/collections
```

Create an API token

In order to call the API, you’ll need to create an API token. Note: tokens can only be created by Account Owners.

  1. Click on the gear icon in the top-right corner. This will take you to the User Access page.

  1. Choose API from the top-left navigation menu.

  1.  Click the + symbol on the right side of the page and give your token a name, like "Demo."


  1.  Copy your token and keep it safe and private as you would a password.

API URL structure

The Impira API uses a common URL structure:

``` language="bash"
https://app.impira.com/o/<YOUR_ORG_NAME>/api/v2/<path>
```

Where <path> specifies the resource you want to read or write to. The API supports different operations through the standard HTTP verbs GET, POST, PATCH, and DELETE. We’ll walk through how to use each of these verbs in depth in the sections that follow.

In most cases:

  • GET allows you to retrieve information about a collection, file, or other resource
  • POST allows you to upload files and insert new records
  • PATCH allows you to update existing records
  • DELETE allows you to delete resources

The following table walks through the different possible values of <path>:

/files

Maps to All files. Use this endpoint to read or write to the full set of files in your organization.

/collection/<collection name>

Maps to a collection named collection name. The upload and write APIs will create this collection automatically if it does not exist.

/fc/<collection id>

Maps to a collection with the specified id. This resembles the URL structure of the Impira app, so you can copy the slug directly from a collection and use it in the API.

/dc/<dataset id >

Maps to a dataset with the specified id. This resembles the URL structure of the Impira app, so you can copy the slug directly from a dataset and use it in the API.

/ec/<entity class name >

Maps to an entity class name, which is the identifier used in IQL to reference an object. Collections, datasets, and even All files are entity classes.

You can use each of the GET, POST, PATCH, and DELETE verbs to read and write files and data at each of these paths.

Uploading files with POST

Uploading files directly to Impira is a breeze. Impira supports two methods to write files through the API:

  1. Submitting a POST request with a file URL and other metadata.
  2. Directly uploading a file as multipart/form-data through a POST request.

Uploading files with URLs

You can upload a file to a given resource (e.g., a collection) by submitting a POST request to the appropriate path. The request takes a JSON object which includes one or more entries to insert. Each entry includes the following information:

  • The File object contains the path to the file and optional metadata fields:
  • File.path is a URL to the file. The file must be accessible to Impira’s cloud-based servers. You can use an HTTP or HTTPS URL, or if your data is public, you can use an Amazon S3 URL.
  • File.name is an optional name for the file which appears in the UI. This name doesn't have to be unique. If you omit the name, the file will appear with an empty name in the UI.
  • If you're uploading to a collection, you can only specify values in the File field. If you'd like to specify values for other fields, you must do that in a follow up PATCH request (see below). You cannot specify ML model (inferred) fields through the API.

Example request

``` language="bash"
curl -X POST "https://app.impira.com:443/o/<YOUR_ORG_HERE>/api/v2/collection/Applications" \
  --header "X-Access-Token: YOUR_TOKEN_HERE" \
  --header "Content-Type: application/json" \
  --data '
{
    "data": [
      {
        "File": {
        "path": "https://assets-global.website-files.com/5e3898dff5077817ea80d71c/6047b3733b9cbd22251c7ef8_Screen%20Shot%202021-03-09%20at%2012.42.02%20PM.png",
        "name": "application form 10"
      }
    },
    ...
  ]
}'
```

Example response

``` language="js"
{
  "uids": [
    "927a834f5f2036e6"
  ]
}
```

Uploading files directly

If you have a file on your local machine or server and want to upload it directly to Impira, you can simply upload it with a multi-part file form submission. The direct file upload API supports up to 10 MB per request, which you can spread across one or more files.

For each file you'd like to upload, you can submit a file form field. You can optionally specify a data field for each file, which is a JSON encoded value that contains any record values to include alongside the file object. Just like URL-based upload, you can only specify fields in the File object (e.g., name). You can edit any follow up fields in a PATCH request.

Example request

```language=“bash”
curl -X POST "https://app.impira.com:443/o/<YOUR_ORG_HERE>/api/v2/collection/Applications" \
  --header "X-Access-Token: YOUR_TOKEN_HERE" \
  --form "file=@local_file.pdf"
```

Example response

``` language="js"
{
  "uids": [
    "8a4dc36aa82bf85b"
  ]
}
```

Example request

``` language=“bash”
curl -X POST https://app.impira.com:443/o/<YOUR_ORG_HERE>/api/v2/collection/Applications \
  --header 'X-Access-Token: YOUR_TOKEN_HERE' \
  --form 'file=@local_file1.pdf' \
  --form 'data={"File": {"name": "my_file_1.pdf"}}' \
  --form 'file=@local_file2.pdf' \
  --form 'data={"File": {"name": "my_file_2.pdf"}}' \
```

Example response

``` language="js"
{
  "uids": [
    "cb713868a5155ad8",
    "f1df198b1ebdef98"
  ]
}
```

Inserting data with POST

You can insert data into a dataset the same way as uploading a file. Unlike writing to /files or a collection, you don't need to include the File object when writing to a dataset. Instead, just specify the fields you want to write.

NOTE: These fields must exist on the dataset. If you try to write data referencing fields that do not exist, you'll receive an error.

Example request

``` language=“bash”
curl -X POST "https://app.impira.com:443/o/<YOUR_ORG_HERE>/api/v2/dc/337dd57d0c5948f9" \
  --header "X-Access-Token: YOUR_TOKEN_HERE" \
  --header "Content-Type: application/json" \
  --data '
{
  "data": [
  {
      "Name": "Rhyley Green"
      "Hired": true,
    },
    {
      "Name": "Ammar Duffy"
      "Hired": false,
    }
    ...
  ]
}'
```

Example response

``` language="js"
{
  "uids": [
      "360fe1982bb9055a",
      "b0694bc41fa6b241"
    ]
}
```

The uid field is a unique identifier for the record you insert. If you do not specify a uid in the request, then Impira will generate one for you. You can use this uid in future requests (or just specify your own) to perform an upsert, which will insert a new record if the uid is not already present or update the record if it is. For example, if the insert above returned a uid of b0694bc41fa6b241 for "Ammar Duffy," then you can run this to update their Hired field to true:

Example request

``` language=“bash”
curl -X POST "https://app.impira.com:443/o/<YOUR_ORG_HERE>/api/v2/dc/337dd57d0c5948f9" \
  --header "X-Access-Token: YOUR_TOKEN_HERE" \
  --header "Content-Type: application/json" \
  --data '
{
  "data": [
    {
      "uid": "b0694bc41fa6b241"
      "Name": "Ammar Duffy"
      "Hired": true,
    }
  ]
}'
```

Example response

``` language="js"
{
  "uids": [
    "b0694bc41fa6b241"
  ]
}
```

NOTE: Unlike a PATCH request which updates a row, you must specify every field in an upsert. For example, if you omit the name field from the above request (e.g., {"uid": "b0694bc41fa6b241", "Hired": true}), then the request will overwrite Name with an empty value.

Updating data

When you insert a new record using a POST request, you can either specify your own uid or Impira will generate one for you if not. You can later use this uid to reference the record and PATCH commands to update it. This method works across both collections and datasets.

For each record in a PATCH request, you must specify the record's uid as well as any fields you'd like to update. This example updates the file we uploaded earlier to set its Inspected state to true.

Example request

``` language=“bash”
curl -X PATCH "https://app.impira.com:443/o/<YOUR_ORG_HERE>/api/v2/collection/Applications" \
  --header "X-Access-Token: YOUR_TOKEN_HERE" \
  --header "Content-Type: application/json" \
  --data '
{
      "data": [
      {
        "uid": "8a4dc36aa82bf85b"
        "Inspected": true,
      },
    ...
  ]
}'
```

Example response

``` language="js"
{
  "uids": [
    "8a4dc36aa82bf85b"
  ]
}
```

Just like a POST request, you can specify multiple records to update in a PATCH. Each record can even contain different fields that you'd like to update.

Deleting files or data

Use the DELETE verb to delete a record from the global set of files, a collection, or a dataset. The payload is the same format as the response from POST and PATCH requests (e.g., a list of uid values that you'd like to delete). For example, to delete the file above globally, you can run:

Example request

``` language=“bash”
curl -X DELETE "https://app.impira.com:443/o/<YOUR_ORG_HERE>/api/v2/files" \
  --header "X-Access-Token: YOUR_TOKEN_HERE" \
  --header "Content-Type: application/json" \
  --data '
{
  "uids": [
    "8a4dc36aa82bf85b"
  ]
}'
```

Example response

``` language="js"
{
  "uids": [
    "8a4dc36aa82bf85b"
 ]
}
```

Deleting from a collection

Just as in the application, if you issue a DELETE against a collection, Impira will remove the file record from the collection but not delete it globally. If you'd like to delete a file globally, then delete it from /files as shown above. This will also remove the file from any collections it belongs to.

Reading files or data

To read data at a given path, you can use the GET verb. You do not need to specify a body for the request. However, you can specify a few optional query parameters:

  • fields is a comma separated list of fields. You can use this to select specific fields. By default, the read API returns all fields in a collection or dataset.
  • include_joins. By default, for performance reasons, the read API does not include joined fields. You can specify include_joins=true to include joined fields.
  • highest and lowest can be used to sort by a particular field. For example, highest=Price will sort records by the highest value of Price first.
  • offset and limit can help paginate long results. offset defines the starting point and limit constrains the total number of records returned. If you use offset and limit to paginate, you should specify a sort via highest or lowest otherwise you may duplicate or miss records.
  • Any other parameters are interpreted as filters. For example, if you have a field named Inspected, you can specify Inspected=true as a query parameter to only include records that have Inspected set to the value true.

Example requests

Return all records in the Applications collection.

``` language="bash"
curl -X GET "https://app.impira.com:443/o/<YOUR_ORG_HERE>/api/v2/files" \
 --header "X-Access-Token: YOUR_TOKEN_HERE"
```

Return all records in the Applications collection.
``` language="bash"
curl -X GET "https://app.impira.com:443/o/<YOUR_ORG_HERE>/api/v2/collection/Applications" \
 --header "X-Access-Token: YOUR_TOKEN_HERE"
```

Return all records in the Applications collection with `Inspected=true`.
``` language="bash"
curl -X GET "https://app.impira.com:443/o/<YOUR_ORG_HERE>/api/v2/collection/Applications?Inspected=true" \
 --header "X-Access-Token: YOUR_TOKEN_HERE"
```

Return 10 records in the Applications collection.

``` language="bash"
curl -X GET "https://app.impira.com:443/o/<YOUR_ORG_HERE>/api/v2/collection/Applications?limit=10" \
 --header "X-Access-Token: YOUR_TOKEN_HERE"
```

Return 10 records in the Applications collection sorted by price.

``` language="bash"
curl -X GET "https://app.impira.com:443/o/<YOUR_ORG_HERE>/api/v2/collection/Applications?limit=10&lowest=Price" \
 --header "X-Access-Token: YOUR_TOKEN_HERE"
```

Using Impira Query Language (IQL)

Impira also supports much more advanced, SQL-like queries over your data. These queries are expressed in a simple language called Impira Query Language (IQL). Please see the linked guide for more details on how to use IQL.