Docs
This page provides technical documentation for the Nyckel Machine Learning API. For Guides and Quickstarts, follow links from the left navigation panel.
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 Security section for you account.
Access tokens expire after one hour. To ensure uninterrupted API access, obtain new tokens as needed.
Create an access token
POST
connect/token
Request
Body
client_id |
The ClientId associated with your user account. | |
Body
client_secret |
The ClientSecret associated with your user account. |
curl -X POST \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'grant_type=client_credentials&client_id=<clientId>&client_secret=<clientSecret>' \ 'https://www.nyckel.com/connect/token'
import requests token_url = 'https://www.nyckel.com/connect/token' data = {'grant_type': 'client_credentials', 'client_id': '<clientId>', 'client_secret': '<clientSecret>'} result = requests.post(token_url, data = data) print(result.text)
fetch('https://www.nyckel.com/connect/token', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: 'grant_type=client_credentials&client_id=<clientId>&client_secret=<clientSecret>' }) .then(response => response.json()) .then(data => console.log(data));
$clientId = '<clientId>'; $clientSecret = '<clientSecret>'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/connect/token'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, 'grant_type=client_credentials&client_id=' . $clientId . '&client_secret=' . $clientSecret); $headers = array(); $headers[] = 'Content-Type: application/x-www-form-urlencoded'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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.
|
{
"access_token": "<accessToken>",
"token_type": "Bearer",
"expires_in": 3600
}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,
Number, and Image.
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-datarequest -
As a data URI
in a
application/jsonrequest
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", ...}).
Keys within the JSON object can be either field ids or field names.
Values within the JSON object must be JSON strings when specifying
Text or Image fields, and JSON numbers when specifying a Number field.
When specifying an image, use either an internet-accessible image url, or provide a data URI.
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. |
Selected responses with suggested actions.
| 402 | Billing issue. Mostly likely because you have exceeded the free tier quota. |
| 403 | Forbidden. Check your credentials. |
| 409 | Resouce conflict. Commonly raised when trying to create a sample that already exists in the function (Nyckel does not allow duplicate samples). When annotating an existing sample, use the PUT samples endpoint instead. |
| 429 | Throttled. You have exceeded either 25 requests per second or 25 concurrent requests. |
| 500 | Internal error. Retry -- ideally with exponential backoff. |
| 503 | Service temporarily unavailable. Retry -- ideally with exponential backoff. |
API Throttling
Nyckel implements two types of throttling: rate-limiting and throttling.
- Rate-limiting imposes a limit on the number of API requests per second (RPS). It is currently set to 25 RPS.
- Concurrency throttling impose a limit on the number of concurrent requests. It is currently set to 25 concurrent requests.
Both limits can be relaxed as part of an Enterprise plan. If you exceed these limits, the API will return a 429 error code.
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.
Context Length
Nyckel's Text and Tabular models rely on (several) Large Language Models (LLMs) to ingest the sample text. Each model has a so-called "context length" which determines how much text it can ingest (and therefore learn from). Currently, the Nyckel LLMs have a context length of 512 "tokens".
A "token" is a word, punctuation, or other language part. There is no simple 1-to-1 mapping between token counts and word or character counts. For example, most tokenizers use one token for the word "cat", but two tokens for "cat's". Moreover, the mapping depends on the "tokenizer" -- a piece of code that converts text into tokens. And the tokenizer depends on the LLM.
In our experiments, using a wide array of texts, we found that the Nyckel LLMs can ingest 300-500 words of text. If your text is longer than that, you have two options
- Try using the full text even though they are long. The first 300-500 words often have enough information for Nyckel to learn a good model.
- Shorten the inputs in pre-processing by splitting long samples into many shorter ones.
Classification Reference
The Nyckel API is comprised of RESTful HTTPS endpoints. The following section details the subset of those endpoints relevant to working with classification functions.
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.
|
|
Query
capture |
Optional
Whether to enable invoke capture for this invoke. Invoke capture saves informative samples captured from your invokes for future annotation. Defaults to true.
|
|
Query
externalId |
Optional
Your unique identifier for this sample. This will be used if this invoke is saved through Invoke Capture. Defaults to null.
|
curl -X POST \ -H 'Authorization: Bearer <accessToken>' \ -H 'Content-Type: application/json' \ -d '{"data":"Your input text here"}' \ '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":"Your input text here"}) 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":"Your input text here"} ) }) .then(response => response.json()) .then(data => console.log(data));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/invoke'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data":"Your input text here"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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.
|
{
"labelName": "Bird",
"labelId": "label_2n5a7za51n329v0l",
"confidence": 0.76
}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.
|
|
Query
capture |
Optional
Whether to enable invoke capture for this invoke. Invoke capture saves informative samples captured from your invokes for future annotation. Defaults to true.
|
|
Query
externalId |
Optional
Your unique identifier for this sample. This will be used if this invoke is saved through Invoke Capture. Defaults to null.
|
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/invoke'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data":"<data>"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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.
|
|
Query
capture |
Optional
Whether to enable invoke capture for this invoke. Invoke capture saves informative samples captured from your invokes for future annotation. Defaults to true.
|
|
Query
externalId |
Optional
Your unique identifier for this sample. This will be used if this invoke is saved through Invoke Capture. Defaults to null.
|
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/invoke'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); $file = curl_file_create(realpath('<fileName>')); $fields = array('data' => $file); curl_setopt($ch, CURLOPT_POSTFIELDS, $fields); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: multipart/form-data'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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.
|
{
"labelName": "Bird",
"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.
|
|
Query
capture |
Optional
Whether to enable invoke capture for this invoke. Invoke capture saves informative samples captured from your invokes for future annotation. Defaults to true.
|
|
Query
externalId |
Optional
Your unique identifier for this sample. This will be used if this invoke is saved through Invoke Capture. Defaults to null.
|
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/invoke'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data":{"field_76jk77g59vawcoz8":"John","field_b2jpqb1r2fsfs2s9":"Doe"}}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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.
|
{
"labelName": "Bird",
"labelId": "label_2n5a7za51n329v0l",
"confidence": 0.76
}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, Number, and Image.
|
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/fields'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"<name>","type":"Text"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Response
| id | The Id of the created field. |
| name | The name of this field. |
| type |
The type of this field. Supported values are Text, Number, and Image.
|
{
"name": "<name>",
"type": "Text",
"id": "field_85osy5xwjcscc08o"
}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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/fields/<fieldId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Response
| id | The Id of the created field. |
| name | The name of this field. |
| type |
The type of this field. Supported values are Text, Number, and Image.
|
{
"name": "<name>",
"type": "Text",
"id": "field_85osy5xwjcscc08o"
}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, Number, and Image.
|
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/fields/<fieldId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT'); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"<name>","type":"Text"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Response
| id | The Id of the created field. |
| name | The name of this field. |
| type |
The type of this field. Supported values are Text, Number, and Image.
|
{
"name": "<name>",
"type": "Text",
"id": "field_85osy5xwjcscc08o"
}List fields
GET
v1/functions/<functionId>/fields
Request
Header
accessToken |
A JWT issued to your application by the Nyckel identity provider | |
Query
count |
Optional
The number of samples to return.
|
|
Query
startIndex |
Optional
The zero-based index of the first result to return. Defaults to 0.
|
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/fields'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Response
Returns an array of Field.
| id | The Id of the created field. |
| name | The name of this field. |
| type |
The type of this field. Supported values are Text, Number, and Image.
|
[
{
"name": "<name>",
"type": "Text",
"id": "field_85osy5xwjcscc08o"
}
]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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/fields/<fieldId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/labels'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"<name>","description":"<description>"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
{
"name": "<name>",
"description": "<description>",
"id": "label_2n5a7za51n329v0l"
}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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/labels/<labelId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
{
"name": "Is a bird",
"id": "label_2n5a7za51n329v0l"
}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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/labels/<labelId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT'); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"<name>","description":"<description>"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
{
"name": "<name>",
"description": "<description>",
"id": "label_2n5a7za51n329v0l"
}List labels
GET
v1/functions/<functionId>/labels
Request
Header
accessToken |
A JWT issued to your application by the Nyckel identity provider | |
Query
count |
Optional
The number of samples to return.
|
|
Query
startIndex |
Optional
The zero-based index of the first result to return. Defaults to 0.
|
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/labels'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
[
{
"name": "Is a bird",
"id": "label_2n5a7za51n329v0l"
}
]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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/labels/<labelId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data":"<data>"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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.
|
{
"data": "<data>",
"id": "sample_2n5a7za51n329v0l"
}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.
|
|
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data":"<data>"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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.
|
|
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>' \ -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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); $file = curl_file_create(realpath('<fileName>')); $fields = array('data' => $file); curl_setopt($ch, CURLOPT_POSTFIELDS, $fields); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: multipart/form-data'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
| annotation |
When the sample is annotated, annotation contains the labelId of the sample.
|
{
"data": "https://pointer/to/image",
"externalId": "MyId-123",
"id": "sample_2n5a7za51n329v0l"
}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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data":{"field_76jk77g59vawcoz8":"John","field_b2jpqb1r2fsfs2s9":"Doe"}}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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.
|
{
"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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
| annotation |
The desired output of the model for this sample as an Annotation object.
|
| prediction |
The model's output for this sample as a Prediction object.
|
| externalId | The externalId provided at sample creation, if any. |
Annotation
| labelId | The Id of the label. |
Prediction
| labelId | The Id of the label. |
| confidence | A value between 0 and 1 indicating the confidence that the predicted label is correct. |
{
"annotation": {
"labelId": "label_2n5a7za51n329v0l"
},
"data": "<sampleData>",
"externalId": "MyId-123",
"id": "sample_2n5a7za51n329v0l",
"prediction": {
"labelId": "label_2n5a7za51n329v0l",
"confidence": 0.76
}
}List samples
GET
v1/functions/<functionId>/samples
Request
Header
accessToken |
A JWT issued to your application by the Nyckel identity provider | |
Query
count |
Optional
The number of samples to return.
|
|
Query
startIndex |
Optional
The zero-based index of the first result to return. Defaults to 0.
|
|
Query
externalId |
Optional
When specified, only return the sample associated with this externalId.
|
|
Query
createdBefore |
Optional
When specified, only return samples created on or before this date.
The date must be in RFC 3339 format (e.g. 2021-04-02).
|
|
Query
createdAfter |
Optional
When specified, only return samples created on or after this date.
The date must be in RFC 3339 format (e.g. 2021-04-02).
|
|
Query
origin |
Optional
When specified, only return the sample associated with this origin.
Accepted values are Unspecified or InvokeCapture.
|
|
Query
annotated |
Optional
Filter the results depending on whether or not the samples are annotated.
When specified, the parameter value must be either true or false.
|
|
Query
predicted |
Optional
Filter the results depending on whether or not the samples are predicted.
When specified, the parameter value must be either true or false.
|
|
Query
annotationLabelId |
Optional
Filter the results to only samples annotated with the provided label id.
|
|
Query
predictionLabelId |
Optional
Filter the results to only samples predicted with the provided label id.
|
|
Query
predictionAndAnnotationAgree |
Optional
Filter the results based on whether or not the sample prediction and annotation agree.
When specified, the parameter value must be either true or false.
|
|
Query
sortBy |
Optional
Order the results based on a property of the samples. Accepted values are
default,
annotation,
creation,
confidence, or
agreement.
|
|
Query
sortOrder |
Optional
Whether to sort the results highest to lowest or lowest to highest. Accepted values are
ascending or
descending.
|
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
| annotation |
The desired output of the model for this sample as an Annotation object.
|
| prediction |
The model's output for this sample as a Prediction object.
|
| externalId | The externalId provided at sample creation, if any. |
Annotation
| labelId | The Id of the label. |
Prediction
| labelId | The Id of the label. |
| confidence | A value between 0 and 1 indicating the confidence that the predicted label is correct. |
[
{
"annotation": {
"labelId": "label_2n5a7za51n329v0l"
},
"data": "<sampleData>",
"externalId": "MyId-123",
"id": "sample_2n5a7za51n329v0l",
"prediction": {
"labelId": "label_2n5a7za51n329v0l",
"confidence": 0.76
}
}
]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)
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples?externalId=<externalId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>/annotation'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT'); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"labelId":"label_2n5a7za51n329v0l"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Response
| labelId | The desired output label id for the sample. |
{
"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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>/annotation'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Get function summary
GET
v1/functions/<functionId>/summary
Retrieve aggregate information about the function.
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>/summary'
import requests url = 'https://www.nyckel.com/v1/functions/<functionId>/summary' headers = { 'Authorization': 'Bearer ' + '<accessToken>', } result = requests.get(url, headers=headers) print(result.text)
fetch('https://www.nyckel.com/v1/functions/<functionId>/summary', { method: 'GET', headers: { 'Authorization': 'Bearer ' + '<accessToken>', } }) .then(response => response.json()) .then(data => console.log(data));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/summary'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Response
| sampleCount | The total number of samples in this function. |
| annotatedSampleCount | The total number of annotated samples in this function. |
| annotatedSampleCountByLabelId | A dictionary of key/value pairs where the keys are label Ids and the values are the number of annotated samples for that label. |
{
"sampleCount": 123,
"annotatedSampleCount": 95,
"annotatedSampleCountByLabelId": {
"label_2n5a7za51n329v0l": 56,
"label_h77q8ylibkv6x730": 39
}
}Tags Reference
The Nyckel API is comprised of RESTful HTTPS endpoints. The following section details the subset of those endpoints relevant to working with classification functions.
Semantic Search Reference
The Nyckel API is comprised of RESTful HTTPS endpoints. The following section details the subset of those endpoints relevant to working with search functions.
Search for similar samples using text
POST
v1/functions/<functionId>/invoke
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 Integer
The number of samples to return, along with their distances. When not specified, only the lowest
distance result is returned. When specified, the value must be between 1 and 100.
|
|
Query
includeData |
Optional Boolean
When set to true, 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/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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/invoke'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data":"<data>"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Response
Returns an array of SearchSample objects
| 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. |
[
{
"sampleId": "<sampleId>",
"distance": 0.86,
"externalId": "<externalId>"
}
]Search for similar samples using an image
POST
v1/functions/<functionId>/invoke
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 Integer
The number of samples to return, along with their distances. When not specified, only the lowest
distance result is returned. When specified, the value must be between 1 and 100.
|
|
Query
includeData |
Optional Boolean
When set to true, 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/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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/invoke'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data":"<data>"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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/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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/invoke'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); $file = curl_file_create(realpath('<fileName>')); $fields = array('data' => $file); curl_setopt($ch, CURLOPT_POSTFIELDS, $fields); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: multipart/form-data'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Response
Returns an array of SearchSample objects
| 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. |
[
{
"sampleId": "<sampleId>",
"distance": 0.86,
"externalId": "<externalId>"
}
]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
|
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data":"<data>"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
{
"data": "<data>",
"id": "sample_2n5a7za51n329v0l"
}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
|
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data":"<data>"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); $file = curl_file_create(realpath('<fileName>')); $fields = array('data' => $file); curl_setopt($ch, CURLOPT_POSTFIELDS, $fields); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: multipart/form-data'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
{
"data": "https://pointer/to/image",
"externalId": "MyId-123",
"id": "sample_2n5a7za51n329v0l"
}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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
{
"data": "<sampleData>",
"externalId": "MyId-123",
"id": "sample_2n5a7za51n329v0l"
}List samples
GET
v1/functions/<functionId>/samples
Request
Header
accessToken |
A JWT issued to your application by the Nyckel identity provider | |
Query
count |
Optional
The number of samples to return.
|
|
Query
startIndex |
Optional
The zero-based index of the first result to return. Defaults to 0.
|
|
Query
externalId |
Optional
When specified, only return the sample associated with this externalId.
|
|
Query
createdBefore |
Optional
When specified, only return samples created on or before this date.
The date must be in RFC 3339 format (e.g. 2021-04-02).
|
|
Query
createdAfter |
Optional
When specified, only return samples created on or after this date.
The date must be in RFC 3339 format (e.g. 2021-04-02).
|
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
[
{
"data": "<sampleData>",
"externalId": "MyId-123",
"id": "sample_2n5a7za51n329v0l"
}
]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)
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples/<sampleId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples?externalId=<externalId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Detection Reference
The Nyckel API is comprised of RESTful HTTPS endpoints. The following section details the subset of those endpoints relevant to working with detection functions.
Basic flow:
- Create a function of with output type
Localization. - Create a label for your function. Note that detection functions only permit one label per function at present.
- Add samples to your function.
- Annotate samples to specify where the objects of interest are.
- Once 2 images have been annotated (not counting zero-object annotations) your function will train. You may have to wait up to 60 seconds for this to complete before calling invoke.
- Call invoke to identify where the objects of interest are in a new image.
Locate objects in an image
POST
v0.9/functions/<functionId>/locate
Request
Locate objects in 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>/locate'
import requests url = 'https://www.nyckel.com/v0.9/functions/<functionId>/locate' 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>/locate', { method: 'POST', headers: { 'Authorization': 'Bearer ' + '<accessToken>', 'Content-Type': 'application/json', }, body: JSON.stringify( {"data": "<data>"} ) }) .then(response => response.json()) .then(data => console.log(data));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v0.9/functions/<functionId>/locate'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data": "<data>"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Locate objects in 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>/locate'
import requests url = 'https://www.nyckel.com/v0.9/functions/<functionId>/locate' 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>/locate', { method: 'POST', headers: { 'Authorization': 'Bearer ' + '<accessToken>', }, body: form }) .then(response => response.json()) .then(data => console.log(data));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v0.9/functions/<functionId>/locate'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); $file = curl_file_create(realpath('<fileName>')); $fields = array('data' => $file); curl_setopt($ch, CURLOPT_POSTFIELDS, $fields); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: multipart/form-data'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Response
An array of
Prediction objectsPrediction
| labelId | The Id of the located label. |
| points |
The list of PointPrediction where the label was predicted to be located.
|
PointPrediction
| confidence | A value between 0 and 1 indicating the confidence that the label was located at the given point, 1 being the most confident. |
| x | The x coordinate of the point expressed as a value between 0 and 1 with 0 being the leftmost edge of the image and 1 being the rightmost edge. |
| y | The y coordinate of the point expressed as a value between 0 and 1 with 0 being the top edge of the image and 1 being the bottom edge. |
[
{
"labelId": "<labelId>",
"points": [
{
"x": 0.25,
"y": 0.78,
"confidence": 0.85
}
]
}
]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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/labels'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"<name>","description":"<description>"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
{
"name": "<name>",
"description": "<description>",
"id": "label_2n5a7za51n329v0l"
}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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/labels/<labelId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
{
"name": "Is a bird",
"id": "label_2n5a7za51n329v0l"
}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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/labels/<labelId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT'); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"<name>","description":"<description>"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
{
"name": "<name>",
"description": "<description>",
"id": "label_2n5a7za51n329v0l"
}List labels
GET
v1/functions/<functionId>/labels
Request
Header
accessToken |
A JWT issued to your application by the Nyckel identity provider | |
Query
count |
Optional
The number of samples to return.
|
|
Query
startIndex |
Optional
The zero-based index of the first result to return. Defaults to 0.
|
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/labels'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
[
{
"name": "Is a bird",
"id": "label_2n5a7za51n329v0l"
}
]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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/labels/<labelId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Create an image sample
POST
v0.9/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
|
curl -X POST \ -H 'Authorization: Bearer <accessToken>' \ -H 'Content-Type: application/json' \ -d '{"data":"<data>"}' \ 'https://www.nyckel.com/v0.9/functions/<functionId>/samples'
import requests url = 'https://www.nyckel.com/v0.9/functions/<functionId>/samples' 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>/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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v0.9/functions/<functionId>/samples'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data":"<data>"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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/v0.9/functions/<functionId>/samples'
import requests url = 'https://www.nyckel.com/v0.9/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/v0.9/functions/<functionId>/samples', { method: 'POST', headers: { 'Authorization': 'Bearer ' + '<accessToken>', }, body: form }) .then(response => response.json()) .then(data => console.log(data));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v0.9/functions/<functionId>/samples'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); $file = curl_file_create(realpath('<fileName>')); $fields = array('data' => $file); curl_setopt($ch, CURLOPT_POSTFIELDS, $fields); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: multipart/form-data'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
{
"data": "https://pointer/to/image",
"externalId": "MyId-123",
"id": "sample_2n5a7za51n329v0l"
}Get a sample
GET
v0.9/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/v0.9/functions/<functionId>/samples/<sampleId>'
import requests url = 'https://www.nyckel.com/v0.9/functions/<functionId>/samples/<sampleId>' headers = { 'Authorization': 'Bearer ' + '<accessToken>', } result = requests.get(url, headers=headers) print(result.text)
fetch('https://www.nyckel.com/v0.9/functions/<functionId>/samples/<sampleId>', { method: 'GET', headers: { 'Authorization': 'Bearer ' + '<accessToken>', } }) .then(response => response.json()) .then(data => console.log(data));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v0.9/functions/<functionId>/samples/<sampleId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
| annotation |
The desired output of the model for this sample as an array of Annotation objects.
|
| prediction |
The model's output for this sample as an array of Prediction objects.
|
| externalId | The externalId provided at sample creation, if any. |
Annotation
| labelId | The Id of the located label. |
| points |
The list of PointAnnotation where the label is annotated to be located.
|
PointAnnotation
| x | The x coordinate of the point expressed as a value between 0 and 1 with 0 being the leftmost edge of the image and 1 being the rightmost edge. |
| y | The y coordinate of the point expressed as a value between 0 and 1 with 0 being the top edge of the image and 1 being the bottom edge. |
Prediction
| labelId | The Id of the located label. |
| points |
The list of PointPrediction where the label was predicted to be located.
|
PointPrediction
| confidence | A value between 0 and 1 indicating the confidence that the label was located at the given point, 1 being the most confident. |
| x | The x coordinate of the point expressed as a value between 0 and 1 with 0 being the leftmost edge of the image and 1 being the rightmost edge. |
| y | The y coordinate of the point expressed as a value between 0 and 1 with 0 being the top edge of the image and 1 being the bottom edge. |
{
"annotation": [
{
"labelId": "2n5a7za51n329v0l",
"points": [
{
"x": 0.123,
"y": 0.789
}
]
}
],
"data": "<sampleData>",
"externalId": "MyId-123",
"id": "sample_2n5a7za51n329v0l",
"prediction": [
{
"labelId": "2n5a7za51n329v0l",
"points": [
{
"x": 0.152,
"y": 0.811,
"confidence": 0.9
}
]
}
]
}List samples
GET
v0.9/functions/<functionId>/samples
Request
Header
accessToken |
A JWT issued to your application by the Nyckel identity provider | |
Query
count |
Optional
The number of samples to return.
|
|
Query
startIndex |
Optional
The zero-based index of the first result to return. Defaults to 0.
|
|
Query
externalId |
Optional
When specified, only return the sample associated with this externalId.
|
|
Query
createdBefore |
Optional
When specified, only return samples created on or before this date.
The date must be in RFC 3339 format (e.g. 2021-04-02).
|
|
Query
createdAfter |
Optional
When specified, only return samples created on or after this date.
The date must be in RFC 3339 format (e.g. 2021-04-02).
|
|
Query
annotated |
Optional
Filter the results depending on whether or not the samples are annotated.
When specified, the parameter value must be either true or false.
|
|
Query
predicted |
Optional
Filter the results depending on whether or not the samples are predicted.
When specified, the parameter value must be either true or false.
|
|
Query
annotationLabelId |
Optional
Filter the results to only samples annotated with the provided label id.
|
|
Query
predictionLabelId |
Optional
Filter the results to only samples predicted with the provided label id.
|
|
Query
predictionAndAnnotationAgree |
Optional
Filter the results based on whether or not the sample prediction and annotation agree.
When specified, the parameter value must be either true or false.
|
|
Query
sortBy |
Optional
Order the results based on a property of the samples. Accepted values are
default,
annotation,
creation,
confidence, or
agreement.
|
|
Query
sortOrder |
Optional
Whether to sort the results highest to lowest or lowest to highest. Accepted values are
ascending or
descending.
|
curl -X GET \ -H 'Authorization: Bearer <accessToken>' \ 'https://www.nyckel.com/v0.9/functions/<functionId>/samples'
import requests url = 'https://www.nyckel.com/v0.9/functions/<functionId>/samples' headers = { 'Authorization': 'Bearer ' + '<accessToken>', } result = requests.get(url, headers=headers) print(result.text)
fetch('https://www.nyckel.com/v0.9/functions/<functionId>/samples', { method: 'GET', headers: { 'Authorization': 'Bearer ' + '<accessToken>', } }) .then(response => response.json()) .then(data => console.log(data));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v0.9/functions/<functionId>/samples'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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. |
| annotation |
The desired output of the model for this sample as an array of Annotation objects.
|
| prediction |
The model's output for this sample as an array of Prediction objects.
|
| externalId | The externalId provided at sample creation, if any. |
Annotation
| labelId | The Id of the located label. |
| points |
The list of PointAnnotation where the label is annotated to be located.
|
PointAnnotation
| x | The x coordinate of the point expressed as a value between 0 and 1 with 0 being the leftmost edge of the image and 1 being the rightmost edge. |
| y | The y coordinate of the point expressed as a value between 0 and 1 with 0 being the top edge of the image and 1 being the bottom edge. |
Prediction
| labelId | The Id of the located label. |
| points |
The list of PointPrediction where the label was predicted to be located.
|
PointPrediction
| confidence | A value between 0 and 1 indicating the confidence that the label was located at the given point, 1 being the most confident. |
| x | The x coordinate of the point expressed as a value between 0 and 1 with 0 being the leftmost edge of the image and 1 being the rightmost edge. |
| y | The y coordinate of the point expressed as a value between 0 and 1 with 0 being the top edge of the image and 1 being the bottom edge. |
[
{
"annotation": [
{
"labelId": "2n5a7za51n329v0l",
"points": [
{
"x": 0.123,
"y": 0.789
}
]
}
],
"data": "<sampleData>",
"externalId": "MyId-123",
"id": "sample_2n5a7za51n329v0l",
"prediction": [
{
"labelId": "2n5a7za51n329v0l",
"points": [
{
"x": 0.152,
"y": 0.811,
"confidence": 0.9
}
]
}
]
}
]Delete a sample
DELETE
v0.9/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/v0.9/functions/<functionId>/samples/<sampleId>'
import requests url = 'https://www.nyckel.com/v0.9/functions/<functionId>/samples/<sampleId>' headers = { 'Authorization': 'Bearer ' + '<accessToken>', } result = requests.delete(url, headers=headers) print(result.text)
fetch('https://www.nyckel.com/v0.9/functions/<functionId>/samples/<sampleId>', { method: 'DELETE', headers: { 'Authorization': 'Bearer ' + '<accessToken>', } }) .then(response => response.json()) .then(data => console.log(data));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v0.9/functions/<functionId>/samples/<sampleId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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/v0.9/functions/<functionId>/samples?externalId=<externalId>'
import requests url = 'https://www.nyckel.com/v0.9/functions/<functionId>/samples?externalId=<externalId>' headers = { 'Authorization': 'Bearer ' + '<accessToken>', } result = requests.delete(url, headers=headers) print(result.text)
fetch('https://www.nyckel.com/v0.9/functions/<functionId>/samples?externalId=<externalId>', { method: 'DELETE', headers: { 'Authorization': 'Bearer ' + '<accessToken>', } }) .then(response => response.json()) .then(data => console.log(data));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v0.9/functions/<functionId>/samples?externalId=<externalId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Set the annotation for a sample
PUT
v0.9/functions/<functionId>/samples/<sampleId>/annotation
Request
An array of Annotation objects that represent the locations of objects in the sample.
Annotation
| labelId | The Id of the located label. |
| points |
The list of PointAnnotation where the label is annotated to be located.
|
PointAnnotation
| x | The x coordinate of the point expressed as a value between 0 and 1 with 0 being the leftmost edge of the image and 1 being the rightmost edge. |
| y | The y coordinate of the point expressed as a value between 0 and 1 with 0 being the top edge of the image and 1 being the bottom edge. |
curl -X PUT \ -H 'Authorization: Bearer <accessToken>' \ -H 'Content-Type: application/json' \ -d '[{"labelId":"2n5a7za51n329v0l","points":[{"x":0.123,"y":0.789}]}]' \ 'https://www.nyckel.com/v0.9/functions/<functionId>/samples/<sampleId>/annotation'
import requests url = 'https://www.nyckel.com/v0.9/functions/<functionId>/samples/<sampleId>/annotation' headers = { 'Authorization': 'Bearer ' + '<accessToken>', } result = requests.put(url, headers=headers, json=[{"labelId":"2n5a7za51n329v0l","points":[{"x":0.123,"y":0.789}]}]) print(result.text)
fetch('https://www.nyckel.com/v0.9/functions/<functionId>/samples/<sampleId>/annotation', { method: 'PUT', headers: { 'Authorization': 'Bearer ' + '<accessToken>', 'Content-Type': 'application/json', }, body: JSON.stringify( [{"labelId":"2n5a7za51n329v0l","points":[{"x":0.123,"y":0.789}]}] ) }) .then(response => response.json()) .then(data => console.log(data));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v0.9/functions/<functionId>/samples/<sampleId>/annotation'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT'); curl_setopt($ch, CURLOPT_POSTFIELDS, '[{"labelId":"2n5a7za51n329v0l","points":[{"x":0.123,"y":0.789}]}]'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Response
An array of Annotation objects now associated with this sample.
Annotation
| labelId | The Id of the located label. |
| points |
The list of PointAnnotation where the label is annotated to be located.
|
PointAnnotation
| x | The x coordinate of the point expressed as a value between 0 and 1 with 0 being the leftmost edge of the image and 1 being the rightmost edge. |
| y | The y coordinate of the point expressed as a value between 0 and 1 with 0 being the top edge of the image and 1 being the bottom edge. |
[
{
"labelId": "2n5a7za51n329v0l",
"points": [
{
"x": 0.123,
"y": 0.789
}
]
}
]Remove the annotation for a sample
DELETE
v0.9/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/v0.9/functions/<functionId>/samples/<sampleId>/annotation'
import requests url = 'https://www.nyckel.com/v0.9/functions/<functionId>/samples/<sampleId>/annotation' headers = { 'Authorization': 'Bearer ' + '<accessToken>', } result = requests.delete(url, headers=headers) print(result.text)
fetch('https://www.nyckel.com/v0.9/functions/<functionId>/samples/<sampleId>/annotation', { method: 'DELETE', headers: { 'Authorization': 'Bearer ' + '<accessToken>', } }) .then(response => response.json()) .then(data => console.log(data));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v0.9/functions/<functionId>/samples/<sampleId>/annotation'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
OCR Reference
The Nyckel API is comprised of RESTful HTTPS endpoints. The following section details the subset of those endpoints relevant to working with OCR functions.
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. | |
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v0.9/functions/<functionId>/ocr'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data": "<data>"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v0.9/functions/<functionId>/ocr'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); $file = curl_file_create(realpath('<fileName>')); $fields = array('data' => $file); curl_setopt($ch, CURLOPT_POSTFIELDS, $fields); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: multipart/form-data'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Response
| text | All extracted text from the image. |
{
"text": "A bird is a common animal."
}Functions Reference
You can use the following endpoints to programmatically create, read, and delete functions.
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, Tags, Search, Localization, and Ocr.
|
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));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"<name>","input":"Text","output":"Classification"}'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; $headers[] = 'Content-Type: application/json'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Response
| id | The Id of the created function. |
| name | The name of this function. |
| input |
The type of input being supplied to this function. Supported values are Text, Image, and Tabular.
|
| output |
The ML technique to apply to the input. Supported values are Classification, Tags, Search, Localization, and Ocr.
|
{
"name": "<name>",
"input": "Text",
"output": "Classification",
"id": "function_85osy5xwjcscc08o"
}Get a function
GET
v1/functions/<functionId>
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>'
import requests url = 'https://www.nyckel.com/v1/functions/<functionId>' headers = { 'Authorization': 'Bearer ' + '<accessToken>', } result = requests.get(url, headers=headers) print(result.text)
fetch('https://www.nyckel.com/v1/functions/<functionId>', { method: 'GET', headers: { 'Authorization': 'Bearer ' + '<accessToken>', } }) .then(response => response.json()) .then(data => console.log(data));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Response
| id | The Id of the created function. |
| name | The name of this function. |
| input |
The type of input being supplied to this function. Supported values are Text, Image, and Tabular.
|
| output |
The ML technique to apply to the input. Supported values are Classification, Tags, Search, Localization, and Ocr.
|
{
"name": "<name>",
"input": "Text",
"output": "Classification",
"id": "function_85osy5xwjcscc08o"
}List functions
GET
v1/functions
Request
Header
accessToken |
A JWT issued to your application by the Nyckel identity provider. | |
Query
count |
Optional
The number of samples to return.
|
|
Query
startIndex |
Optional
The zero-based index of the first result to return. Defaults to 0.
|
curl -X GET \ -H 'Authorization: Bearer <accessToken>' \ 'https://www.nyckel.com/v1/functions'
import requests url = 'https://www.nyckel.com/v1/functions' headers = { 'Authorization': 'Bearer ' + '<accessToken>', } result = requests.get(url, headers=headers) print(result.text)
fetch('https://www.nyckel.com/v1/functions', { method: 'GET', headers: { 'Authorization': 'Bearer ' + '<accessToken>', } }) .then(response => response.json()) .then(data => console.log(data));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;
Response
Returns an array of Function objects.
| id | The Id of the created function. |
| name | The name of this function. |
| input |
The type of input being supplied to this function. Supported values are Text, Image, and Tabular.
|
| output |
The ML technique to apply to the input. Supported values are Classification, Tags, Search, Localization, and Ocr.
|
[
{
"name": "<name>",
"input": "Text",
"output": "Classification",
"id": "function_85osy5xwjcscc08o"
}
]Delete a function
DELETE
v1/functions/<functionId>
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>'
import requests url = 'https://www.nyckel.com/v1/functions/<functionId>' headers = { 'Authorization': 'Bearer ' + '<accessToken>', } result = requests.delete(url, headers=headers) print(result.text)
fetch('https://www.nyckel.com/v1/functions/<functionId>', { method: 'DELETE', headers: { 'Authorization': 'Bearer ' + '<accessToken>', } }) .then(response => response.json()) .then(data => console.log(data));
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE'); $headers = array(); $headers[] = 'Authorization: Bearer ' . '<accessToken>'; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $result = curl_exec($ch); curl_close($ch); echo $result;