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.

POST connect/token

Create an access token

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.

POST v1/functions/<functionId>/invoke

Invoke a text function

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, along with their confidences, to return (defaults to 1)
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.
{
  "labelName": "True",
  "labelId": "label_2n5a7za51n329v0l",
  "confidence": 0.76
}
POST v1/functions/<functionId>/invoke

Invoke an image function

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.
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.
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.
{
  "labelName": "True",
  "labelId": "label_2n5a7za51n329v0l",
  "confidence": 0.76
}
POST v1/functions/<functionId>/invoke

Invoke a tabular function

Header
accessToken
A JWT issued to your application by the Nyckel identity provider
Body
data
The tabular input for the function.
curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"data":{"FirstName":"John","LastName":"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":{"FirstName":"John","LastName":"Doe"}})
print(result.text)
labelName The tabular 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.
{
  "labelName": "True",
  "labelId": "label_2n5a7za51n329v0l",
  "confidence": 0.76
}
POST v1/functions/<functionId>/fields

Create a field

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 v1/functions/<functionId>/fields/<fieldId>

Get a field

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"
}
PUT v1/functions/<functionId>/fields/<fieldId>

Update a field

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"
}
GET v1/functions/<functionId>/fields

List fields

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 v1/functions/<functionId>/fields/<fieldId>

Delete a field

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)
POST v1/functions/<functionId>/labels

Create a label

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.
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.
{
  "id": "label_2n5a7za51n329v0l",
  "name": "<name>",
  "description": "<description>"
}
GET v1/functions/<functionId>/labels/<labelId>

Get a label

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.
{
  "id": "label_2n5a7za51n329v0l",
  "name": "Is a bird",
  "description": null
}
PUT v1/functions/<functionId>/labels/<labelId>

Update a label

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.
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.
{
  "id": "label_2n5a7za51n329v0l",
  "name": "<name>",
  "description": "<description>"
}
GET v1/functions/<functionId>/labels

List labels

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.
[
  {
    "id": "label_2n5a7za51n329v0l",
    "name": "Is a bird",
    "description": null
  }
]
DELETE v1/functions/<functionId>/labels/<labelId>

Delete a label

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)
POST v1/functions/<functionId>/samples

Create a text sample

Header
accessToken
A JWT issued to your application by the Nyckel identity provider
Body
data
The text input for the 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.
{
  "id": "sample_2n5a7za51n329v0l",
  "prediction": null,
  "annotation": null,
  "data": "<data>"
}
POST v1/functions/<functionId>/samples

Create an image sample

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.
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.
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.
{
  "id": "sample_2n5a7za51n329v0l",
  "prediction": null,
  "annotation": null,
  "data": "..."
}
POST v1/functions/<functionId>/samples

Create a tabular sample

Header
accessToken
A JWT issued to your application by the Nyckel identity provider
Body
data
The tabular input for the sample.
curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"data":{"FirstName":"John","LastName":"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":{"FirstName":"John","LastName":"Doe"}})
print(result.text)
id The Id of the created sample.
data The tabular input data associated with this sample.
{
  "id": "sample_2n5a7za51n329v0l",
  "annotation": null,
  "prediction": null,
  "data": {
    "field_76jk77g59vawcoz8": "John",
    "field_b2jpqb1r2fsfs2s9": "Doe"
  }
}
GET v1/functions/<functionId>/samples/<sampleId>

Get a sample

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.
{
  "id": "sample_2n5a7za51n329v0l",
  "prediction": {
    "labelId": "label_2n5a7za51n329v0l",
    "confidence": 0.76
  },
  "annotation": {
    "labelId": "label_2n5a7za51n329v0l"
  },
  "data": "Example input data text"
}
GET v1/functions/<functionId>/samples

List samples

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.
[
  {
    "id": "sample_2n5a7za51n329v0l",
    "prediction": {
      "labelId": "label_2n5a7za51n329v0l",
      "confidence": 0.76
    },
    "annotation": {
      "labelId": "label_2n5a7za51n329v0l"
    },
    "data": "Example input data text"
  }
]
DELETE v1/functions/<functionId>/samples/<sampleId>

Delete a sample

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)
PUT v1/functions/<functionId>/samples/<sampleId>/annotation

Set the annotation for a sample

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"
}
DELETE v1/functions/<functionId>/samples/<sampleId>/annotation

Remove the annotation for a sample

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)