Guides
Concepts
Endpoints

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)
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. 
{
  "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:

  1. Raw image bytes as part of a multipart/form-data request
  2. 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:

  1. As a URL which points to the image resource
  2. 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.

Endpoints Reference

The Nyckel API is comprised of RESTful HTTPS endpoints. They are detailed in the following sections.

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)
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. 
{
  "labelName": "True",
  "labelId": "label_2n5a7za51n329v0l",
  "confidence": 0.76,
  "labelConfidences": null
}

Invoke an image function

POST v1/functions/<functionId>/invoke
Request

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)

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)
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. 
{
  "labelName": "True",
  "labelId": "label_2n5a7za51n329v0l",
  "confidence": 0.76,
  "labelConfidences": null
}

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)
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. 
{
  "labelName": "True",
  "labelId": "label_2n5a7za51n329v0l",
  "confidence": 0.76,
  "labelConfidences": null
}

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)
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. 
{
  "searchSamples": [
    {
      "sampleId": "<sampleId>",
      "distance": 0.86,
      "externalId": "<externalId>",
      "data": null
    }
  ]
}

Search for similar samples using an image

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

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)

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)
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. 
{
  "searchSamples": [
    {
      "sampleId": "<sampleId>",
      "distance": 0.86,
      "externalId": "<externalId>"
    }
  ]
}

Extract text from an image

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

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. 
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)

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. 
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)
text All extracted text from the image. 
{
  "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)
id The Id of the created field.
name The name of this field. 
{
  "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)
id The Id of the created field.
name The name of this field.
type The data type of this field. 
{
  "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)
id The Id of the created field.
name The name of this field.
type The data type of this field. 
{
  "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
Body
batchSize
Optional
The number of fields to return.
Body
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)

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. 
[
  {
    "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)

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)
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. 
{
  "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)
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. 
{
  "id": "label_2n5a7za51n329v0l",
  "name": "Is a bird",
  "description": null
}

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)
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. 
{
  "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
Body
batchSize
Optional
The number of labels to return.
Body
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)

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. 
[
  {
    "id": "label_2n5a7za51n329v0l",
    "name": "Is a bird",
    "description": null
  }
]

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)

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. 
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)
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. 
{
  "id": "sample_2n5a7za51n329v0l",
  "prediction": null,
  "annotation": null,
  "data": "<data>",
  "externalId": null
}

Create an image sample

POST v1/functions/<functionId>/samples
Request

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
Body
annotation.labelId
Optional
The Id of the label to associate with 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)

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.
Body
annotation.labelId
Optional
The Id of the label to associate with 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)
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.
annotation When the sample is annotated, annotation contains the labelId of the sample. 
{
  "id": "sample_2n5a7za51n329v0l",
  "prediction": null,
  "annotation": null,
  "data": "https://pointer/to/image",
  "externalId": "<externalId>"
}

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. 
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)
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. 
{
  "id": "sample_2n5a7za51n329v0l",
  "data": {
    "field_76jk77g59vawcoz8": "John",
    "field_b2jpqb1r2fsfs2s9": "Doe"
  },
  "externalId": null,
  "annotation": null
}

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)
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.
annotation The desired output of the model for this sample.
prediction The model's output for this sample.
externalId The externalId provided at sample creation, if any. 
{
  "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
Body
batchSize
Optional
The number of samples to return.
Body
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. 
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)

Returns an array of Sample.

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.
annotation The desired output of the model for this sample.
prediction The model's output for this sample.
externalId The externalId provided at sample creation, if any. 
[
  {
    "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

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)

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)

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		 The desired output of your function. 
curl -X PUT \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"labelId":"<labelId>"}' \
  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":"<labelId>"})
print(result.text)
labelId The desired output of your function. 
{
  "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)

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)
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. 
{
  "id": "85osy5xwjcscc08o",
  "name": "<name>",
  "input": "Text",
  "output": "Classification"
}