Notebook Actions

https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID

Below are the various requests that can be performed against the Notebook resource, as well as the expected parameters and the potential responses.

Cancel Execution

Marks a specific notebook execution for cancellation

Method And Url

POST https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID/cancelExecution

Authentication

A valid API access token is required to access this endpoint. The token must include at least one of the following scopes: all.Application, all.Organization, all.User, notebook.*, or notebook.execute.

Request Path Components

Path Component	Description	Example
APPLICATION_ID	ID associated with the application	575ec8687ae143cd83dc4a97
NOTEBOOK_ID	ID associated with the notebook	575ed78e7ae143cd83dc4aab

Request Query Parameters

Name	Required	Description	Default	Example
executionId	Y	The ID of the execution to cancel		executionId=632e18632f59592e773a4153

Request Headers

Name	Required	Description	Default
Authorization	Y	The token for authenticating the request, prepended with Bearer

Curl Example

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X POST \
    https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID/cancelExecution?executionId=632e18632f59592e773a4153

Successful Responses

Code	Type	Description
200	Success	If the execution was successfully marked for cancellation

Error Responses

Code	Type	Description
400	Error	Error if malformed request
404	Error	Error if execution was not found

Delete

Deletes a notebook

Method And Url

DELETE https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID

Authentication

A valid API access token is required to access this endpoint. The token must include at least one of the following scopes: all.Application, all.Organization, all.User, notebook.*, or notebook.delete.

Request Path Components

Path Component	Description	Example
APPLICATION_ID	ID associated with the application	575ec8687ae143cd83dc4a97
NOTEBOOK_ID	ID associated with the notebook	575ed78e7ae143cd83dc4aab

Request Headers

Name	Required	Description	Default
Authorization	Y	The token for authenticating the request, prepended with Bearer

Curl Example

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X DELETE \
    https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID

Successful Responses

Code	Type	Description
200	Success	If notebook was successfully deleted

Error Responses

Code	Type	Description
400	Error	Error if malformed request
404	Error	Error if notebook was not found

Execute

Triggers the execution of a notebook

Method And Url

POST https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID/execute

Authentication

A valid API access token is required to access this endpoint. The token must include at least one of the following scopes: all.Application, all.Organization, all.User, notebook.*, or notebook.execute.

Request Path Components

Path Component	Description	Example
APPLICATION_ID	ID associated with the application	575ec8687ae143cd83dc4a97
NOTEBOOK_ID	ID associated with the notebook	575ed78e7ae143cd83dc4aab

Request Headers

Name	Required	Description	Default
Authorization	Y	The token for authenticating the request, prepended with Bearer

Request Body

The body of the request should be serialized JSON that validates against the Notebook Execution Options schema. For example, the following would be a valid body for this request:

{
  "relativeTo": 1570549199451
}

Curl Example

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X POST \
    -d '{"relativeTo":1570549199451}' \
    https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID/execute

Successful Responses

Code	Type	Description
200	Success With Execution ID	If execution request was accepted and successfully queued

Error Responses

Code	Type	Description
400	Error	Error if malformed request
404	Error	Error if notebook was not found

Get

Retrieves information on a notebook

Method And Url

GET https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID

Authentication

A valid API access token is required to access this endpoint. The token must include at least one of the following scopes: all.Application, all.Application.read, all.Organization, all.Organization.read, all.User, all.User.read, notebook.*, or notebook.get.

Request Path Components

Path Component	Description	Example
APPLICATION_ID	ID associated with the application	575ec8687ae143cd83dc4a97
NOTEBOOK_ID	ID associated with the notebook	575ed78e7ae143cd83dc4aab

Request Headers

Name	Required	Description	Default
Authorization	Y	The token for authenticating the request, prepended with Bearer

Curl Example

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X GET \
    https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID

Successful Responses

Code	Type	Description
200	Notebook	notebook information

Error Responses

Code	Type	Description
400	Error	Error if malformed request
404	Error	Error if notebook was not found

Logs

Retrieves information on notebook executions

Method And Url

GET https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID/logs

Authentication

A valid API access token is required to access this endpoint. The token must include at least one of the following scopes: all.Application, all.Application.read, all.Organization, all.Organization.read, all.User, all.User.read, notebook.*, or notebook.logs.

Request Path Components

Path Component	Description	Example
APPLICATION_ID	ID associated with the application	575ec8687ae143cd83dc4a97
NOTEBOOK_ID	ID associated with the notebook	575ed78e7ae143cd83dc4aab

Request Query Parameters

Name	Required	Description	Default	Example
limit	N	Max log entries to return (ordered by time descending)	1	limit=10
since	N	Look for log entries since this time (ms since epoch)		since=1465790400000

Request Headers

Name	Required	Description	Default
Authorization	Y	The token for authenticating the request, prepended with Bearer

Curl Example

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X GET \
    https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID/logs

Successful Responses

Code	Type	Description
200	Notebook Execution Logs	notebook execution information

Error Responses

Code	Type	Description
400	Error	Error if malformed request
404	Error	Error if notebook was not found

Notebook Minute Counts

Returns notebook execution usage by day for the time range specified for this notebook

Method And Url

GET https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID/notebookMinuteCounts

Authentication

A valid API access token is required to access this endpoint. The token must include at least one of the following scopes: all.Application, all.Application.read, all.Organization, all.Organization.read, all.User, all.User.read, notebook.*, or notebook.notebookMinuteCounts.

Request Path Components

Path Component	Description	Example
APPLICATION_ID	ID associated with the application	575ec8687ae143cd83dc4a97
NOTEBOOK_ID	ID associated with the notebook	575ed78e7ae143cd83dc4aab

Request Query Parameters

Name	Required	Description	Default	Example
start	N	Start of range for notebook execution query (ms since epoch)		start=0
end	N	End of range for notebook execution query (ms since epoch)		end=1465790400000

Request Headers

Name	Required	Description	Default
Authorization	Y	The token for authenticating the request, prepended with Bearer

Curl Example

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X GET \
    https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID/notebookMinuteCounts

Successful Responses

Code	Type	Description
200	Notebook Minute Counts	Notebook usage information

Error Responses

Code	Type	Description
400	Error	Error if malformed request
404	Error	Error if notebook was not found

Patch

Updates information about a notebook

Method And Url

PATCH https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID

Authentication

A valid API access token is required to access this endpoint. The token must include at least one of the following scopes: all.Application, all.Organization, all.User, notebook.*, or notebook.patch.

Request Path Components

Path Component	Description	Example
APPLICATION_ID	ID associated with the application	575ec8687ae143cd83dc4a97
NOTEBOOK_ID	ID associated with the notebook	575ed78e7ae143cd83dc4aab

Request Headers

Name	Required	Description	Default
Authorization	Y	The token for authenticating the request, prepended with Bearer

Request Body

The body of the request should be serialized JSON that validates against the Notebook Patch schema. For example, the following would be a valid body for this request:

{
  "name": "New Notebook Name"
}

Curl Example

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X PATCH \
    -d '{"name":"New Notebook Name"}' \
    https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID

Successful Responses

Code	Type	Description
200	Notebook	Updated notebook information

Error Responses

Code	Type	Description
400	Error	Error if malformed request
404	Error	Error if notebook was not found

Request Input Data Export

Requests a combined zip file of the potential input data for a notebook execution

Method And Url

POST https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID/requestInputDataExport

Authentication

A valid API access token is required to access this endpoint. The token must include at least one of the following scopes: all.Application, all.Application.read, all.Organization, all.Organization.read, all.User, all.User.read, notebook.*, or notebook.requestInputDataExport.

Request Path Components

Path Component	Description	Example
APPLICATION_ID	ID associated with the application	575ec8687ae143cd83dc4a97
NOTEBOOK_ID	ID associated with the notebook	575ed78e7ae143cd83dc4aab

Request Headers

Name	Required	Description	Default
Authorization	Y	The token for authenticating the request, prepended with Bearer

Request Body

The body of the request should be serialized JSON that validates against the Notebook Data Export Options schema. For example, the following would be a valid body for this request:

{
  "email": "user@example.com"
}

Curl Example

curl -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X POST \
    -d '{"email":"user@example.com"}' \
    https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID/requestInputDataExport

Successful Responses

Code	Type	Description
202	Job Enqueued API Result	If export request was accepted and successfully queued

Error Responses

Code	Type	Description
400	Error	Error if malformed request
404	Error	Error if notebook was not found

Upload

Uploads the jupyter notebook file

Method And Url

POST https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID/upload

Authentication

A valid API access token is required to access this endpoint. The token must include at least one of the following scopes: all.Application, all.Organization, all.User, notebook.*, or notebook.upload.

Request Path Components

Path Component	Description	Example
APPLICATION_ID	ID associated with the application	575ec8687ae143cd83dc4a97
NOTEBOOK_ID	ID associated with the notebook	575ed78e7ae143cd83dc4aab

Request Headers

Name	Required	Description	Default
Authorization	Y	The token for authenticating the request, prepended with Bearer

Request Body

The body of the request should be a multipart form data post containing the following:

Name	Required	Description	Default	Example
jupyterFile	Y	The jupyter notebook file		``

Curl Example

curl -H 'Content-Type: multipart/form-data' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
    -X POST \
    -F jupyterFile=@localfilename' \
    https://api.losant.com/applications/APPLICATION_ID/notebooks/NOTEBOOK_ID/upload

Successful Responses

Code	Type	Description
200	Notebook	Updated notebook information

Error Responses

Code	Type	Description
400	Error	Error if malformed request
404	Error	Error if notebook was not found

Schemas

Error

Schema for errors returned by the API

Error Schema

▶
root:{} 3 keys
$schema:"http://json-schema.org/draft-07/schema#"
type:"object"
▶
properties:{} 2 keys
▶
type:{} 1 key
▶
message:{} 1 key

Error Example

▶
root:{} 2 keys
type:"NotFound"
message:"Application was not found"

Job Enqueued API Result

Schema for the result of a job being queued

Job Enqueued API Result Schema

▶
root:{} 3 keys
$schema:"http://json-schema.org/draft-07/schema#"
type:"object"
▶
properties:{} 3 keys
▶
jobQueued:{} 2 keys
▶
jobId:{} 2 keys
▶
success:{} 2 keys

Job Enqueued API Result Example

▶
root:{} 3 keys
jobQueued:true
jobId:"clnHvJbyVkOWAZwYAwLP4"
success:true

Notebook

Schema for a single Notebook

Notebook Schema

▶
root:{} 3 keys
$schema:"http://json-schema.org/draft-07/schema#"
type:"object"
▶
properties:{} 13 keys
▶
id:{} 2 keys
▶
notebookId:{} 2 keys
▶
applicationId:{} 2 keys
▶
creationDate:{} 2 keys
▶
lastUpdated:{} 2 keys
▶
name:{} 3 keys
▶
description:{} 2 keys
▶
jupyterFileName:{} 3 keys
▶
jupyterFileUrl:{} 1 key
▶
imageVersion:{} 2 keys
▶
inputs:{} 2 keys
▶
outputs:{} 2 keys
▶
stats:{} 3 keys

Notebook Example

▶
root:{} 11 keys
id:"5c782b8d4f3a8e51c1db42e4"
notebookId:"5c782b8d4f3a8e51c1db42e4"
applicationId:"575ec8687ae143cd83dc4a97"
creationDate:"2016-06-13T04:00:00.000Z"
lastUpdated:"2016-06-13T04:00:00.000Z"
name:"Example Notebook"
jupyterFileName:"myNotebook.ipynb"
jupyterFileUrl:"https:/storage.example.com/myNotebook.ipynb"
▶
inputs:[] 5 items
▶
outputs:[] 9 items
▶
stats:{} 3 keys

Notebook Data Export Options

Schema for the options for a Notebook data export request

Notebook Data Export Options Schema

▶
root:{} 4 keys
$schema:"http://json-schema.org/draft-07/schema#"
type:"object"
▶
properties:{} 4 keys
▶
email:{} 3 keys
▶
relativeTo:{} 1 key
▶
templateContext:{} 2 keys
▶
callbackUrl:{} 3 keys
additionalProperties:false

Notebook Data Export Options Example

▶
root:{} 1 key
email:"user@example.com"

Notebook Execution Logs

Schema for a set of Notebook execution logs

Notebook Execution Logs Schema

▶
root:{} 3 keys
$schema:"http://json-schema.org/draft-07/schema#"
type:"array"
▶
items:{} 2 keys

Notebook Execution Logs Example

▶
root:[] 1 item
▶
0:{} 13 keys

Notebook Execution Options

Schema for the options for a Notebook execution request

Notebook Execution Options Schema

▶
root:{} 4 keys
$schema:"http://json-schema.org/draft-07/schema#"
type:"object"
▶
properties:{} 4 keys
▶
relativeTo:{} 1 key
▶
templateContext:{} 2 keys
▶
email:{} 3 keys
▶
callbackUrl:{} 3 keys
additionalProperties:false

Notebook Execution Options Example

▶
root:{} 1 key
relativeTo:1570549199451

Notebook Minute Counts

Schema for the result of a notebook minute counts request

Notebook Minute Counts Schema

▶
root:{} 3 keys
$schema:"http://json-schema.org/draft-07/schema#"
type:"object"
▶
properties:{} 3 keys
▶
start:{} 2 keys
▶
end:{} 2 keys
▶
counts:{} 2 keys

Notebook Minute Counts Example

▶
root:{} 3 keys
start:"1999-05-20T05:00:00.000Z"
end:"1999-06-20T04:59:59.999Z"
▶
counts:[] 1 item

Notebook Patch

Schema for the body of a Notebook modification request

Notebook Patch Schema

▶
root:{} 4 keys
$schema:"http://json-schema.org/draft-07/schema#"
type:"object"
▶
properties:{} 5 keys
▶
name:{} 3 keys
▶
description:{} 2 keys
▶
inputs:{} 2 keys
▶
outputs:{} 2 keys
▶
imageVersion:{} 2 keys
additionalProperties:false

Notebook Patch Example

▶
root:{} 1 key
name:"New Notebook Name"

Success

Schema for reporting a successful operation

Success Schema

▶
root:{} 3 keys
$schema:"http://json-schema.org/draft-07/schema#"
type:"object"
▶
properties:{} 1 key
▶
success:{} 2 keys

Success Example

▶
root:{} 1 key
success:true

Success With Execution ID

Schema for reporting a successful operation with a corresponding execution ID

Success With Execution ID Schema

▶
root:{} 3 keys
$schema:"http://json-schema.org/draft-07/schema#"
type:"object"
▶
properties:{} 2 keys
▶
success:{} 2 keys
▶
executionId:{} 2 keys

Success With Execution ID Example

▶
root:{} 2 keys
success:true
executionId:"575ed78e7ae143cd83dc4aab"