API Docs | Nyckel

Authentication

Requests to the Nyckel API must be authenticated. Requests are authenticated by providing an Authorization header with a JWT access token.

Access tokens are obtained by calling the connect/token endpoint, and the required secrets are available in the API tab for your function.

Create an access token

POST connect/token

Request

Body authority	The OAuth Authority associated with this function. This value is specific to your function.
Body client_id	The ClientId associated with this function. This value is specific to your function.
Body client_secret	The ClientSecret associated with this function. This value is specific to your function.

curl -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=<clientId>&client_secret=<clientSecret>&grant_type=client_credentials' \
  <authority>/connect/token

import requests

token_url = '<authority>/connect/token'
data = {'client_id': '<clientId>', 'client_secret': '<clientSecret>', 'grant_type': 'client_credentials'}

result = requests.post(token_url, data = data)
print(result.text)

fetch('<authority>/connect/token', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: 'client_id=<clientId>&client_secret=<clientSecret>&grant_type=client_credentials'
})
.then(response => response.json())
.then(data => console.log(data));

Response

access_token	A securty token that can be used to authorize API requests.
token_type	The type of token. The value will be `Bearer` for Nyckel functions.
expires_in	The number of seconds before the provided `access_token` expires.

Example Response

{
  "access_token": "<accessToken>",
  "token_type": "Bearer",
  "expires_in": 86400
}

Data Types

Nyckel supports three input data types: Text, Image, and Tabular. The Tabular input data type contains a list of fields which can be of type Text or Number. Endpoint requests and responses that pass sample or invoke data will differ based on the data type.

Text

Requests that pass Text data must send the text as a JSON string.

Responses that pass Text data will send the text as a JSON string.

Image

Requests that pass Image data can be provided in two ways:

Raw image bytes as part of a multipart/form-data request
As a data URI in a application/json request

Responses that pass Image data will be provided as a JSON string with one of two formats:

As a URL which points to the image resource
As a data URI which contains the image data

Tabular

Requests that pass Tabular data must send the text as a JSON object (e.g. {"key": "value", ...}). Values within the JSON object must be JSON strings or numbers.

Responses that pass Tabular data will send the text as a JSON object. Values within the JSON object will be JSON strings or numbers.

Error responses

In addition to 2xx responses, each endpoint can return various 4xx and 5xx responses. All error responses have the same response schema:

4xx or 5xx Response

message

A textual description of the error encountered.

Prefixes

API endpoints return Id fields which contain human-readable prefixes, followed by an underscore, followed by an alpha-numeric Id. Although it is not strictly necessary to send the prefix when calling API endpoints, we recommend you treat the entire string, including the prefix, as the Id for better readability.

Accuracy

When training a function, your function accuracy is shown in the left navigation panel of the console. The top bar reflects the overall accuracy, which is the number of correctly predicted samples divided by the total number of samples. Below are the class level accuracy bars. These show, for each class, how many samples from that class the function predicted correctly.

Cross Validation

To estimate the function accuracy Nyckel uses a strategy called cross-validation. Cross-validation means training multiple models, each trained on most, but not all, of the samples. Each model then predicts the label for all samples that weren't in it's training set. Put together, this strategy provides fair predictions on all annotated data, as well as a good estimate of function accuracy. After cross-validation a final model is trained using all annotated data. This model is used when predicting new data.

Training Data

Nyckel uses the imported and annotated data to train the function. To ensure best performance follow these guidelines when choosing the data to import:

Provide data similar to what your function will encounter in production. If possible, provide data from the same system in which the function will be deployed.
Provide balanced data. Include roughly the same amount of samples from all classes you want your function to predict.
Provide more data. More data is better when training a function.

Invoke a text function

POST v1/functions/<functionId>/invoke

Request

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Body data	The text input for the function.
Query labelCount	Optional The number of labels to return, along with their confidences. When not specified, only the highest confidence result is returned.
Query includeMetadata	Optional Whether to include the label metadata in the response. Defaults to `false`.

curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"data":"<data>"}' \
  https://www.nyckel.com/v1/functions/<functionId>/invoke

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/invoke'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"data":"<data>"})
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/invoke', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"data":"<data>"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

Response

labelName	The text representation of the output label.
labelId	The Id of the label in the functions label list.
confidence	How certain the function is in the provided output.
labelConfidences	A list of the top N most confident labels, where N is `labelCount` from the request. This field is only populated when `labelCount` is specified.
labelMetadata	A dictionary of key/value pairs you can use to store additional information about this label. This field is only populated when `includeMetadata` is specified.

Example Response

{
  "labelName": "True",
  "labelId": "label_2n5a7za51n329v0l",
  "confidence": 0.76
}

Invoke an image function

POST v1/functions/<functionId>/invoke

Request

Send URL
Send Image Bytes

Invoke with an image URL using the application/json content type.

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Body data	A URL pointing to the image. A data URI is also accepted.
Query labelCount	Optional The number of labels to return, along with their confidences. When not specified, only the highest confidence result is returned.
Query includeMetadata	Optional Whether to include the label metadata in the response. Defaults to `false`.

curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"data":"<data>"}' \
  https://www.nyckel.com/v1/functions/<functionId>/invoke

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/invoke'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"data":"<data>"})
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/invoke', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"data":"<data>"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

Invoke with binary image data using the multipart/form-data content type.

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Body fileName	The path to the image file to use as input.
Query labelCount	Optional The number of labels to return, along with their confidences. When not specified, only the highest confidence result is returned.
Query includeMetadata	Optional Whether to include the label metadata in the response. Defaults to `false`.

curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -F 'data=@<fileName>' \
  https://www.nyckel.com/v1/functions/<functionId>/invoke

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/invoke'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

with open('<fileName>', 'rb') as f:
    result = requests.post(url, headers=headers, files={'data': f})
print(result.text)

const form = new FormData();
form.append('data', File(<fileBytes>, '<fileName>'));

fetch('https://www.nyckel.com/v1/functions/<functionId>/invoke', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
    },
    body: form
})
.then(response => response.json())
.then(data => console.log(data));

Response

labelName	The text representation of the output label.
labelId	The Id of the label in the functions label list.
confidence	How certain the function is in the provided output.
labelConfidences	A list of the top N most confident labels, where N is `labelCount` from the request. This field is only populated when `labelCount` is specified.
labelMetadata	A dictionary of key/value pairs you can use to store additional information about this label. This field is only populated when `includeMetadata` is specified.

Example Response

{
  "labelName": "True",
  "labelId": "label_2n5a7za51n329v0l",
  "confidence": 0.76
}

Invoke a tabular function

POST v1/functions/<functionId>/invoke

Request

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Body data	The tabular input for the function.
Query labelCount	Optional The number of labels to return, along with their confidences. When not specified, only the highest confidence result is returned.
Query includeMetadata	Optional Whether to include the label metadata in the response. Defaults to `false`.

curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"data":{"field_76jk77g59vawcoz8":"John","field_b2jpqb1r2fsfs2s9":"Doe"}}' \
  https://www.nyckel.com/v1/functions/<functionId>/invoke

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/invoke'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"data":{"field_76jk77g59vawcoz8":"John","field_b2jpqb1r2fsfs2s9":"Doe"}})
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/invoke', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"data":{"field_76jk77g59vawcoz8":"John","field_b2jpqb1r2fsfs2s9":"Doe"}}
    )
})
.then(response => response.json())
.then(data => console.log(data));

Response

labelName	The text representation of the output label.
labelId	The Id of the label in the functions label list.
confidence	How certain the function is in the provided output.
labelConfidences	A list of the top N most confident labels, where N is `labelCount` from the request. This field is only populated when `labelCount` is specified.
labelMetadata	A dictionary of key/value pairs you can use to store additional information about this label. This field is only populated when `includeMetadata` is specified.

Example Response

{
  "labelName": "True",
  "labelId": "label_2n5a7za51n329v0l",
  "confidence": 0.76
}

Search for similar samples using text

POST v0.9/functions/<functionId>/search

Request

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Body data	The text to use in the search.
Query sampleCount	Optional The number of samples to return, along with their distances. When not specified, only the lowest distance result is returned.
Query includeData	Optional When specified, returns the image or text data for each similar sample.

curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"data":"<data>"}' \
  https://www.nyckel.com/v0.9/functions/<functionId>/search

import requests

url = 'https://www.nyckel.com/v0.9/functions/<functionId>/search'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"data":"<data>"})
print(result.text)

fetch('https://www.nyckel.com/v0.9/functions/<functionId>/search', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"data":"<data>"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

Response

searchSamples An array of SearchSample objects

SearchSample

sampleId	The Id of the search sample.
externalId	Your unique identifier for the search sample (if provided when inserting the sample)
distance	A decimal number indicating how similar this sample is to the probe sample. The smaller the distance, the more similar the samples.

Example Response

{
  "searchSamples": [
    {
      "sampleId": "<sampleId>",
      "distance": 0.86,
      "externalId": "<externalId>"
    }
  ]
}

Search for similar samples using an image

POST v0.9/functions/<functionId>/search

Request

Send URL
Send Image Bytes

Search for similar samples with an image URL using the application/json content type.

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Body data	A URL pointing to the image. A data URI is also accepted.
Query sampleCount	Optional The number of samples to return, along with their distances. When not specified, only the lowest distance result is returned.
Query includeData	Optional When specified, returns the image or text data for each similar sample.

curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"data":"<data>"}' \
  https://www.nyckel.com/v0.9/functions/<functionId>/search

import requests

url = 'https://www.nyckel.com/v0.9/functions/<functionId>/search'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"data":"<data>"})
print(result.text)

fetch('https://www.nyckel.com/v0.9/functions/<functionId>/search', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"data":"<data>"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

Search for similar samples with binary image data using the multipart/form-data content type.

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Body fileName	The path to the image file to use as input.
Query sampleCount	Optional The number of samples to return, along with their distances. When not specified, only the lowest distance result is returned.
Query includeData	Optional When specified, returns the image or text data for each similar sample.

curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -F 'data=@<fileName>' \
  https://www.nyckel.com/v0.9/functions/<functionId>/search

import requests

url = 'https://www.nyckel.com/v0.9/functions/<functionId>/search'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

with open('<fileName>', 'rb') as f:
    result = requests.post(url, headers=headers, files={'data': f})
print(result.text)

const form = new FormData();
form.append('data', File(<fileBytes>, '<fileName>'));

fetch('https://www.nyckel.com/v0.9/functions/<functionId>/search', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
    },
    body: form
})
.then(response => response.json())
.then(data => console.log(data));

Response

searchSamples An array of SearchSample objects

SearchSample

sampleId	The Id of the search sample.
externalId	Your unique identifier for the search sample (if provided when inserting the sample)
distance	A decimal number indicating how similar this sample is to the probe sample. The smaller the distance, the more similar the samples.

Example Response

{
  "searchSamples": [
    {
      "sampleId": "<sampleId>",
      "distance": 0.86,
      "externalId": "<externalId>"
    }
  ]
}

Extract text from an image

POST v0.9/functions/<functionId>/ocr

Request

Send URL
Send Image Bytes

Extract text from an image URL using the application/json content type.

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Body data	A URL pointing to the image. A data URI is also accepted.
Query includeRegions	Optional When set to `true`, return the regions of the image that contained text.

curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"data": "<data>"}' \
  https://www.nyckel.com/v0.9/functions/<functionId>/ocr

import requests

url = 'https://www.nyckel.com/v0.9/functions/<functionId>/ocr'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"data": "<data>"})
print(result.text)

fetch('https://www.nyckel.com/v0.9/functions/<functionId>/ocr', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"data": "<data>"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

Extract text from binary image data using the multipart/form-data content type.

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Body fileName	The path to the image file to use as input.
Query includeRegions	Optional When set to `true`, return the regions of the image that contained text.

curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -F 'data=@<fileName>' \
  https://www.nyckel.com/v0.9/functions/<functionId>/ocr

import requests

url = 'https://www.nyckel.com/v0.9/functions/<functionId>/ocr'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

with open('<fileName>', 'rb') as f:
    result = requests.post(url, headers=headers, files={'data': f})
print(result.text)

const form = new FormData();
form.append('data', File(<fileBytes>, '<fileName>'));

fetch('https://www.nyckel.com/v0.9/functions/<functionId>/ocr', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
    },
    body: form
})
.then(response => response.json())
.then(data => console.log(data));

Response

text	All extracted text from the image.

Example Response

{
  "text": "A bird is a common animal."
}

Create a field

POST v1/functions/<functionId>/fields

Request

Header accessToken	A JWT issued to your application by the Nyckel identity provider.
Body name	The name of this field.
Body type	The type of this field. Supported values are `Text` and `Number`.

curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"<name>","type":"Text"}' \
  https://www.nyckel.com/v1/functions/<functionId>/fields

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/fields'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"name":"<name>","type":"Text"})
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/fields', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"name":"<name>","type":"Text"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

Response

id	The Id of the created field.
name	The name of this field.

Example Response

{
  "id": "field_85osy5xwjcscc08o",
  "name": "<name>",
  "type": "Text"
}

Get a field

GET v1/functions/<functionId>/fields/<fieldId>

Request

Header

accessToken

A JWT issued to your application by the Nyckel identity provider

curl -X GET \
  -H 'Authorization: Bearer <accessToken>' \
  https://www.nyckel.com/v1/functions/<functionId>/fields/<fieldId>

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/fields/<fieldId>'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.get(url, headers=headers)
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/fields/<fieldId>', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
    }
})
.then(response => response.json())
.then(data => console.log(data));

Response

id	The Id of the created field.
name	The name of this field.
type	The data type of this field.

Example Response

{
  "id": "field_85osy5xwjcscc08o",
  "name": "<name>",
  "type": "Text"
}

Update a field

PUT v1/functions/<functionId>/fields/<fieldId>

Request

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Body name	The name of this field.
Body type	The type of this field. Supported values are `Text` and `Number`.

curl -X PUT \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"<name>","type":"Text"}' \
  https://www.nyckel.com/v1/functions/<functionId>/fields/<fieldId>

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/fields/<fieldId>'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.put(url, headers=headers, json={"name":"<name>","type":"Text"})
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/fields/<fieldId>', {
    method: 'PUT',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"name":"<name>","type":"Text"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

Response

id	The Id of the created field.
name	The name of this field.
type	The data type of this field.

Example Response

{
  "id": "field_85osy5xwjcscc08o",
  "name": "<name>",
  "type": "Text"
}

List fields

GET v1/functions/<functionId>/fields

Request

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Query batchSize	Optional The number of fields to return.
Query cursor	Optional When reading subsequent pages of data, use `cursor` to indicate the Id of the last field already read in order to receive the next set of results.

curl -X GET \
  -H 'Authorization: Bearer <accessToken>' \
  https://www.nyckel.com/v1/functions/<functionId>/fields

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/fields'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.get(url, headers=headers)
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/fields', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
    }
})
.then(response => response.json())
.then(data => console.log(data));

Response

Returns an array of Label.

id	The Id of the created field.
name	The name of this field.
type	The data type of this field.

Example Response

[
  {
    "id": "field_85osy5xwjcscc08o",
    "name": "<name>",
    "type": "Text"
  }
]

Delete a field

DELETE v1/functions/<functionId>/fields/<fieldId>

Request

Header

accessToken

A JWT issued to your application by the Nyckel identity provider

curl -X DELETE \
  -H 'Authorization: Bearer <accessToken>' \
  https://www.nyckel.com/v1/functions/<functionId>/fields/<fieldId>

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/fields/<fieldId>'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.delete(url, headers=headers)
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/fields/<fieldId>', {
    method: 'DELETE',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
    }
})
.then(response => response.json())
.then(data => console.log(data));

Create a label

POST v1/functions/<functionId>/labels

Request

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Body name	The name of this label.
Body description	Optional The description of this label.
Body metadata	Optional A dictionary of key/value pairs you can use to store additional information about this label.

curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"<name>","description":"<description>"}' \
  https://www.nyckel.com/v1/functions/<functionId>/labels

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/labels'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"name":"<name>","description":"<description>"})
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/labels', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"name":"<name>","description":"<description>"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

Response

id	The Id of the created label.
name	The name of this label.
description	The description of this label.
metadata	A dictionary of key/value pairs you can use to store additional information about this label.

Example Response

{
  "id": "label_2n5a7za51n329v0l",
  "name": "<name>",
  "description": "<description>"
}

Get a label

GET v1/functions/<functionId>/labels/<labelId>

Request

Header

accessToken

A JWT issued to your application by the Nyckel identity provider

curl -X GET \
  -H 'Authorization: Bearer <accessToken>' \
  https://www.nyckel.com/v1/functions/<functionId>/labels/<labelId>

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/labels/<labelId>'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.get(url, headers=headers)
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/labels/<labelId>', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
    }
})
.then(response => response.json())
.then(data => console.log(data));

Response

id	The Id of the created label.
name	The name of this label.
description	The description of this label.
metadata	A dictionary of key/value pairs you can use to store additional information about this label.

Example Response

{
  "id": "label_2n5a7za51n329v0l",
  "name": "Is a bird"
}

Update a label

PUT v1/functions/<functionId>/labels/<labelId>

Request

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Body name	The name of this label.
Body description	Optional The description of this label.
Body metadata	Optional A dictionary of key/value pairs you can use to store additional information about this label.

curl -X PUT \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"<name>","description":"<description>"}' \
  https://www.nyckel.com/v1/functions/<functionId>/labels/<labelId>

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/labels/<labelId>'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.put(url, headers=headers, json={"name":"<name>","description":"<description>"})
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/labels/<labelId>', {
    method: 'PUT',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"name":"<name>","description":"<description>"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

Response

id	The Id of the created label.
name	The name of this label.
description	The description of this label.
metadata	A dictionary of key/value pairs you can use to store additional information about this label.

Example Response

{
  "id": "label_2n5a7za51n329v0l",
  "name": "<name>",
  "description": "<description>"
}

List labels

GET v1/functions/<functionId>/labels

Request

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Query batchSize	Optional The number of labels to return.
Query cursor	Optional When reading subsequent pages of data, use `cursor` to indicate the Id of the last label already read in order to receive the next set of results.

curl -X GET \
  -H 'Authorization: Bearer <accessToken>' \
  https://www.nyckel.com/v1/functions/<functionId>/labels

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/labels'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.get(url, headers=headers)
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/labels', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
    }
})
.then(response => response.json())
.then(data => console.log(data));

Response

Returns an array of Label.

id	The Id of the created label.
name	The name of this label.
description	The description of this label.
metadata	A dictionary of key/value pairs you can use to store additional information about this label.

Example Response

[
  {
    "id": "label_2n5a7za51n329v0l",
    "name": "Is a bird"
  }
]

Delete a label

DELETE v1/functions/<functionId>/labels/<labelId>

Request

Header

accessToken

A JWT issued to your application by the Nyckel identity provider

curl -X DELETE \
  -H 'Authorization: Bearer <accessToken>' \
  https://www.nyckel.com/v1/functions/<functionId>/labels/<labelId>

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/labels/<labelId>'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.delete(url, headers=headers)
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/labels/<labelId>', {
    method: 'DELETE',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
    }
})
.then(response => response.json())
.then(data => console.log(data));

Create a text sample

POST v1/functions/<functionId>/samples

Request

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Body data	The text input for the sample.
Body externalId	Optional Your unique identifier for this sample
Body annotation.labelId	Optional The Id of the label to associate with this sample.
Body annotation.labelName	Optional The name of the label to associate with this sample. This field is ignored if `annotation.labelId` is specified.

curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"data":"<data>"}' \
  https://www.nyckel.com/v1/functions/<functionId>/samples

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/samples'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"data":"<data>"})
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/samples', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"data":"<data>"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

Response

id	The Id of the created sample.
data	The text input data associated with this sample.
externalId	Your unique identifier for this sample, when provided.
annotation	When the sample is annotated, `annotation` contains the `labelId` of the sample.

Example Response

{
  "id": "sample_2n5a7za51n329v0l",
  "data": "<data>"
}

Create an image sample

POST v1/functions/<functionId>/samples

Request

Send URL
Send Image Bytes

Create a sample with an image URL using the application/json content type.

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Body data	A URL pointing to the image. A data URI is also accepted.
Body externalId	Optional Your unique identifier for this sample

curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"data":"<data>"}' \
  https://www.nyckel.com/v1/functions/<functionId>/samples

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/samples'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"data":"<data>"})
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/samples', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"data":"<data>"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

Create a sample with binary image data using the multipart/form-data content type.

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Body fileName	The path to the image file to associate with this sample.
Body externalId	Optional Your unique identifier for this sample.

curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -F 'data=@<fileName>' \
  https://www.nyckel.com/v1/functions/<functionId>/samples

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/samples'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

with open('<fileName>', 'rb') as f:
    result = requests.post(url, headers=headers, files={'data': f})
print(result.text)

const form = new FormData();
form.append('data', File(<fileBytes>, '<fileName>'));

fetch('https://www.nyckel.com/v1/functions/<functionId>/samples', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
    },
    body: form
})
.then(response => response.json())
.then(data => console.log(data));

Response

id	The Id of the created sample.
data	The input data associated with this sample. This property will either provide a URL to the image, or contain the image inline using the data URI format.
externalId	Your unique identifier for this sample, when provided.

Example Response

{
  "id": "sample_2n5a7za51n329v0l",
  "data": "https://pointer/to/image",
  "externalId": "MyId-123"
}

Create a tabular sample

POST v1/functions/<functionId>/samples

Request

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Body data	The tabular input for the sample.
Body externalId	Optional Your unique identifier for this sample
Body annotation.labelId	Optional The Id of the label to associate with this sample.
Body annotation.labelName	Optional The name of the label to associate with this sample. This field is ignored if `annotation.labelId` is specified.

curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"data":{"field_76jk77g59vawcoz8":"John","field_b2jpqb1r2fsfs2s9":"Doe"}}' \
  https://www.nyckel.com/v1/functions/<functionId>/samples

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/samples'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"data":{"field_76jk77g59vawcoz8":"John","field_b2jpqb1r2fsfs2s9":"Doe"}})
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/samples', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"data":{"field_76jk77g59vawcoz8":"John","field_b2jpqb1r2fsfs2s9":"Doe"}}
    )
})
.then(response => response.json())
.then(data => console.log(data));

Response

id	The Id of the created sample.
data	The tabular input data associated with this sample.
externalId	Your unique identifier for this sample, when provided.
annotation	When the sample is annotated, `annotation` contains the `labelId` of the sample.

Example Response

{
  "id": "sample_2n5a7za51n329v0l",
  "data": {
    "field_76jk77g59vawcoz8": "John",
    "field_b2jpqb1r2fsfs2s9": "Doe"
  }
}

Get a sample

GET v1/functions/<functionId>/samples/<sampleId>

Request

Header

accessToken

A JWT issued to your application by the Nyckel identity provider

curl -X GET \
  -H 'Authorization: Bearer <accessToken>' \
  https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.get(url, headers=headers)
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
    }
})
.then(response => response.json())
.then(data => console.log(data));

Response

id	The Id of the created sample.
data	The input data for this sample. The value stored in this field depends on the input type specified at function creation. See data types for more information.
externalId	The externalId provided at sample creation, if any.

Example Response

{
  "id": "sample_2n5a7za51n329v0l",
  "prediction": {
    "labelId": "label_2n5a7za51n329v0l",
    "confidence": 0.76
  },
  "annotation": {
    "labelId": "label_2n5a7za51n329v0l"
  },
  "data": "<sampleData>",
  "externalId": "MyId-123"
}

List samples

GET v1/functions/<functionId>/samples

Request

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Query batchSize	Optional The number of samples to return.
Query cursor	Optional When reading subsequent pages of data, use `cursor` to indicate the Id of the last sample already read in order to receive the next set of results.
Query externalId	Optional When specified, only return the sample associated with this `externalId`.

curl -X GET \
  -H 'Authorization: Bearer <accessToken>' \
  https://www.nyckel.com/v1/functions/<functionId>/samples

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/samples'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.get(url, headers=headers)
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/samples', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
    }
})
.then(response => response.json())
.then(data => console.log(data));

Response

Returns an array of Sample objects.

id	The Id of the created sample.
data	The input data for this sample. The value stored in this field depends on the input type specified at function creation. See data types for more information.
externalId	The externalId provided at sample creation, if any.

Example Response

[
  {
    "id": "sample_2n5a7za51n329v0l",
    "prediction": {
      "labelId": "label_2n5a7za51n329v0l",
      "confidence": 0.76
    },
    "annotation": {
      "labelId": "label_2n5a7za51n329v0l"
    },
    "data": "<sampleData>",
    "externalId": "MyId-123"
  }
]

Delete a sample

DELETE v1/functions/<functionId>/samples/<sampleId>

Request

By Id
By ExternalId

Delete a sample by Id

Header

accessToken

A JWT issued to your application by the Nyckel identity provider

curl -X DELETE \
  -H 'Authorization: Bearer <accessToken>' \
  https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.delete(url, headers=headers)
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>', {
    method: 'DELETE',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
    }
})
.then(response => response.json())
.then(data => console.log(data));

Delete a sample by ExternalId

Header

accessToken

A JWT issued to your application by the Nyckel identity provider

curl -X DELETE \
  -H 'Authorization: Bearer <accessToken>' \
  https://www.nyckel.com/v1/functions/<functionId>/samples?externalId=<externalId>

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/samples?externalId=<externalId>'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.delete(url, headers=headers)
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/samples?externalId=<externalId>', {
    method: 'DELETE',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
    }
})
.then(response => response.json())
.then(data => console.log(data));

Set the annotation for a sample

PUT v1/functions/<functionId>/samples/<sampleId>/annotation

Request

Header accessToken	A JWT issued to your application by the Nyckel identity provider
Body labelId	Optional The Id of the label to associate with this sample.
Body labelName	Optional The name of the label to associate with this sample. This field is ignored if `labelId` is specified.

curl -X PUT \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"labelId":"label_2n5a7za51n329v0l"}' \
  https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>/annotation

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>/annotation'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.put(url, headers=headers, json={"labelId":"label_2n5a7za51n329v0l"})
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>/annotation', {
    method: 'PUT',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"labelId":"label_2n5a7za51n329v0l"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

Response

labelId

The desired output label id for the sample.

Example Response

{
  "labelId": "label_2n5a7za51n329v0l"
}

Remove the annotation for a sample

DELETE v1/functions/<functionId>/samples/<sampleId>/annotation

Request

Header

accessToken

A JWT issued to your application by the Nyckel identity provider

curl -X DELETE \
  -H 'Authorization: Bearer <accessToken>' \
  https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>/annotation

import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>/annotation'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.delete(url, headers=headers)
print(result.text)

fetch('https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>/annotation', {
    method: 'DELETE',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
    }
})
.then(response => response.json())
.then(data => console.log(data));

Create a function

POST v1/functions

Request

Header accessToken	A JWT issued to your application by the Nyckel identity provider.
Body name	Optional The name of this function.
Body input	The type of input being supplied to this function. Supported values are `Text`, `Image`, and `Tabular`.
Body output	The ML technique to apply to the input. Supported values are `Classification` and `Search`.

curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"<name>","input":"Text","output":"Classification"}' \
  https://www.nyckel.com/v1/functions

import requests

url = 'https://www.nyckel.com/v1/functions'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"name":"<name>","input":"Text","output":"Classification"})
print(result.text)

fetch('https://www.nyckel.com/v1/functions', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"name":"<name>","input":"Text","output":"Classification"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

Response

id	The Id of the created function.
name	The name of this function.
Body input	The type of input being supplied to this function. Supported values are `Text`, `Image`, and `Tabular`.
Body output	The ML technique to apply to the input. Supported values are `Classification`, `Search`, and `Ocr`.

Example Response

{
  "id": "85osy5xwjcscc08o",
  "name": "<name>",
  "input": "Text",
  "output": "Classification"
}

Docs

Authentication

Create an access token

Data Types

Text

Image

Tabular

Error responses

Prefixes

Accuracy

Cross Validation

Training Data

Endpoints Reference

Invoke a text function

Invoke an image function

Invoke a tabular function

Search for similar samples using text

Search for similar samples using an image

Extract text from an image

Create a field

Get a field

Update a field

List fields

Delete a field

Create a label

Get a label

Update a label

List labels

Delete a label

Create a text sample

Create an image sample

Create a tabular sample

Get a sample

List samples

Delete a sample

Set the annotation for a sample

Remove the annotation for a sample

Create a function