Guides
Topics
Resources

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

Request
authority The OAuth Authority associated with this function. This value is specific to your function.
client_id The ClientId associated with this function. This value is specific to your function.
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
}

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.

POST v1/functions/<functionId>/invoke

Invoke a text function

Request
accessToken A JWT issued to your application by the Nyckel identity provider
data The text input for the function. 
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

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

result = requests.post(invoke_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

Request
accessToken A JWT issued to your application by the Nyckel identity provider
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

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

with open('<fileName>', 'rb') as f:
    result = requests.post(invoke_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>/labels

Create a label

Request
accessToken A JWT issued to your application by the Nyckel identity provider
name The name of this label.
description 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
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
}
GET v1/functions/<functionId>/labels/<labelId>

Get a label

Request
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>
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>/label

Update a label

Request
accessToken A JWT issued to your application by the Nyckel identity provider
name The name of this label.
description 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>
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
}
GET v1/functions/<functionId>/labels

List labels

Request
accessToken A JWT issued to your application by the Nyckel identity provider
batchSize The number of labels to return.
cursor 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

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

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

Create a text sample

Request
accessToken A JWT issued to your application by the Nyckel identity provider
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

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

result = requests.post(invoke_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": "Example input data text"
}
POST v1/functions/<functionId>/samples

Create an image sample

Samples with image data can be uploaded in a multipart/form-data request.

Request
accessToken A JWT issued to your application by the Nyckel identity provider
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

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

with open('<fileName>', 'rb') as f:
    result = requests.post(invoke_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": "..."
}
GET v1/functions/<functionId>/samples/<sampleId>

Get a sample

Request
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>
id The Id of the created sample.
data The text input data associated with this sample.
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

Request
accessToken A JWT issued to your application by the Nyckel identity provider
batchSize The number of samples to return.
cursor 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

Returns an array of Sample.

id The Id of the created sample.
data The text input data associated with this sample.
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

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

Set the annotation for a sample

Request
accessToken A JWT issued to your application by the Nyckel identity provider
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
labelId The desired output of your function. 
{
  "labelId": "label_2n5a7za51n329v0l"
}
DELETE v1/functions/<functionId>/samples/<sampleId>/annotation

Remove the annotation for a sample

Request
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