Application Protocol Interface (API)
The Scramjet Cloud Platform API enables programmatic access to SCP in a unique and advanced ways. With this ability a user can get, post, put, and delete a Sequence. SCP supports cURL command-line transfer library to transfer data to and from SCP and in addition to that Scramjet Cloud Platform (SCP) adheres to the Representational state transfer (REST) API protocol and architecture which includes following methods:
Methods
- [ GET ] - All operations requesting data from the Scramjet Cloud Platform (SCP).
- [ POST ] - Creating a new Hub, Sequence, or for messaging and streaming data to a Sequence.
- [ PUT ] - Updating existing Sequences or Instances,
- [ DELETE ] - Removing operations on a Hub or a Space.
Authorization
In order for a user to access Scramjet Cloud platform through Rest API using the cURL command-line, the following basic procedure must be included. A user must carry out the same procedure for the rest of cURL command-lines. Defining the request as follows:
| Section | Content |
|---|---|
| Base URL: | https ://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1 |
| Method: | GET, POST, PUT, or DELETE |
| Headers: | -H "accept: */*" -H "authorization: Bearer <Generated-Token>" -H "content-type: media-type" |
Sequence Store operations
Store Base URL: https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1
[ GET ] {API Base}/s3 - list all Sequences
HTTP request
curl -v --location --request GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/s3" -H "Authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
[ PUT ] {API Base}/s3 - add a Sequences
HTTP request
curl -v --location --request PUT --upload-file "Path/to/filename.tar.gz" "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/s3" -H "accept: */*" -H "Authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "Content-Type: application/octet-stream" -H "Transfer-Encoding: chunked"
[ DELETE ] {API Base}/s3/filename.tar.gz - delete a Sequences
HTTP request
curl -v --request DELETE "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/s3/<filename.tar.gz>" -H "Authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
[ GET ] {API Base}/s3/filename.tar.gz - download a Sequences
HTTP request
curl --location --request GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/s3/<filename.tar.gz>" -H "Authorization: Bearer <GENERATED-TOKEN>" --output "Path/to/downloads/<filename.tar.gz>"
NOTE: Sequences stored on the Sequence Store can be started through an assigned Space-id and Hub-id by including the <Sequence-id> of a Sequence listed undernear the Sequence store listings to the Sequence start API endpoint. The Sequences stored on the Sequence Store will remain available even if they were deleted from a Hub.
Space operations
Space Base URL: https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1
[ GET ] {API Base}/version - show space version
HTTP request
curl -v --location --request GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/version" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
[ GET ] {API Base}/load - show space load info
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/load" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
[ GET ] {API Base}/list - list space Hubs
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/list" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
[ GET ] {API Base}/sequences - show all Sequences on Space
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sequences" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/json"
[ GET ] {API Base}/instances - show list of Instances on Space
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/instances" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/json"
[ GET ] {API Base}/log - show logs form Space
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/log" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/json"
Responses
Content-type: application/octet-stream
[ GET ] {API Base}/sth/:id/info - show the Hub info
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/info" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/json"
Hub operations
Hub Base URL: https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1
[ GET ] {API Base}/version - show the Hub version
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/version" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
[ GET ] {API Base}/config - show the Hub config
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/config" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
[ GET ] {API Base}/load-check - monitor CPU, memory and disk usage metrics on the Hub machine
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/load-check" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
[ GET ] {API Base}/log - show logs form Hub
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/log" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
[ GET ] {API Base}/topics - list Space Topics
HTTP request
curl --location --request GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/topics" -H "accept: */*" -H "Authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/json"
[ POST ] {API Base}/topic/:name - sends data to the Topic, if it does not exist, the Topic is created
HTTP request
curl -v --location --data "<STRING>" "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/topic/<TOPIC-NAME>" -H "accept: */*" -H "Authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/json"
Request Headers
Content-type: application/x-ndjson
Responses
Status: 200 - Success - when data to topic is sent with the header indicating the end of data
Status: 202 - accepted - when data to topic is sent without the header indicating the end of data (default)
[ GET ] {API Base}/topic/:name - get data from the Topic
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/topic/<TOPIC-NAME>" -H "accept: */*" -H "Authorization: Bearer <GENERATED-TOKEN>"
Sequence operations
Sequence Base URL: https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1
[ GET ] {API Base}/sequences - show all Sequences saved on the Hub
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/sequences" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
[ GET ] {API Base}/sequence/:id - show Sequence details
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/sequence/<SEQUENCE-ID>" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
[ GET ] {API Base}/sequence/:id/instances - show Instances of a Sequence
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/sequence/<SEQUENCE-ID>/instances" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
[ POST ] {API Base}/sequence - add new Sequence
Parameters
| Name | Description | Type | Required |
|---|---|---|---|
| file | compressed package in tar.gz format | binary | yes |
| appConfig | additional package.json config file | json | no |
| x-name | alias name for sequence | header | no |
HTTP request
curl -v --location --request POST --upload-file "PATH/TO/filename.tar.gz" "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/sequence" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "Content-Type: application/octet-stream" -H "Transfer-Encoding: chunked"
[ PUT ] {API Base}/sequence/:id_name - update exising Sequence
Parameters
| Name | Description | Type | Required |
|---|---|---|---|
| file | compressed package in tar.gz format | binary | yes |
| appConfig | additional package.json config file | json | no |
| x-name | alias name for sequence | header | no |
[ POST ] {API Base}/sequence/:id/start - start chosen Sequence
Parameters
| Name | Description | Type | Required |
|---|---|---|---|
| appConfig | additional package.json config file | json | no |
| args | additional arguments that instance should starts with | json | no |
HTTP request
curl -v --location --request POST "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/sequence/<SEQUENCE-ID>/start" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/json"
[ DELETE ] {API Base}/sequence/:id - delete a Sequence by Sequence-id
Note: If an Instance is started from a given Sequence, the Sequence can not be removed.
HTTP request
curl -v --location --request DELETE "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/sequence/<SEQUENCE-ID>" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
Instance operations
Instance Base URL: https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1
[ GET ] {API Base}/instances - show list of Instances running on the Hub
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instances" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
[ GET ] {API Base}/instance/:id - show data of a chosen Instance
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
[ POST ] {API Base}/instance/:id/_stop - end an Instance gracefully, prolongs an operation to be completed
Parameters
| Name | Description | Type | Required |
|---|---|---|---|
| timeout | The number of milliseconds before the Instance will be killed. Default: 7000ms. | number | no |
| canCallKeepalive | If set to true, the instance will prolong the running. Default: false. | boolean | no |
HTTP request
curl -v --location --request POST "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/_stop" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
[ POST ] {API Base}/instance/:id/_kill - end an Instance gracefully while waiting for an unfinished task
HTTP request
curl -v --location --request POST "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/_kill" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
[ GET ] {API Base}/instance/:id/health - check health status of an Instance
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/health" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json"
[ POST ] {API Base}/instance/:id/input - send data to the Instance
HTTP request
- Input data as a string
curl -v --data "<STRING>" POST "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/input" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "Content-Type: text/plain"
- Input data from a file
curl -v --request POST --upload-file "Path/to/file.txt" "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/input" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "Content-Type: text/plain"
- Input data through keyboard
curl -v -X POST --include "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/input" --header "Content-Type: text/plain" --header "Transfer-Encoding: chunked" -H "authorization: Bearer <GENERATED-TOKEN>" --no-buffer -T -
[ GET ] {API Base}/instance/:id/output - get the output stream from the Instance
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/output" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/json"
[ POST ] {API Base}/instance/:id/stdin - process.stdin
HTTP request
curl -v --request POST --upload-file "Path/to/file.txt" "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/stdin" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "Transfer-Encoding: chunked" -H "content-type: application/octet-stream"
[ GET ] {API Base}/instance/:id/stdout - process.stdout
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/stdout" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "Transfer-Encoding: chunked" -H "content-type: application/octet-stream"
[ GET ] {API Base}/instance/:id/stderr - process.stderr
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/stderr" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "Transfer-Encoding: chunked" -H "content-type: application/octet-stream"
[ GET ] {API Base}/instance/:id/log - stream all instance logs
HTTP request
curl -v --location GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/log" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>"
[ POST ] {API Base}/instance/:id/_event - send an Event to the Instance
Parameters
| Name | Type | Description | Required |
|---|---|---|---|
eventName |
string |
Name of an event | true |
message |
string |
JSON formatted event payload | false |
HTTP request
curl --location --request POST "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/_event" -H "authorization: Bearer <GENERATED-TOKEN>" -H "content-type: application/json" --data-raw "[5001,{\"eventName\": \"<NAMED-EVENT>\" ,\"message\": \"<SENT-MESSAGE>\"}]"
[ GET ] {API Base}/instance/:id/event - get the data stream with the Events from the Instance
HTTP request
curl --location --request GET "https://api.scramjet.cloud/api/v1/space/<SPACE-ID>/api/v1/sth/<STH-ID>/api/v1/instance/<INSTANCE-ID>/event/<EVENT-RESPONSE-NAME>" -H "accept: */*" -H "authorization: Bearer <GENERATED-TOKEN>" -H "cache-control: no-cache" -H "content-type: application/octet-stream"
[ GET ] {API Base}/instance/:id/once - get the last Event sent by the Instance
Headers
Content-type: application/octet-stream
The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are defined by RFC7231 and registered status codes are listed in the IANA Status Code Registry.
The most common HTTP status codes handled by requested Scramjet endpoints are placed in the table below as part of the REST methods returning HTTP status codes, notifying the calling client of the failure or success of the REST request.
| Status code | Description |
|---|---|
| 200 Success | The request completed successfully. |
| 202 Accepted | The request has been accepted for processing, but the processing has not been completed. |
| 204 No Content | The request completed successfully, but content is not available. |
| 400 Bad Request | The REST request contains parameters that are not valid or missing. |
| 401 Unauthorized | The caller is not authorized to perform the request. |
| 403 Forbidden | The caller is not authorized to complete the request. |
| 404 Not Found | The requested resource does not exist. |
| 406 Not Acceptable | The request contains an unsupported content type or content encoding. |
| 412 Invalid syntax | The request uses an invalid regular expression in the fieldname parameter for collection types. |
| 419 Insufficient Resources | Insufficient RAM memory availability. |
| 422 Unprocessable Entity | Error encountered when unpacking a sequence. |
| 500 Internal Server Error | A problem has occurred. Additional information is provided in the stack trace. |
Useful hints for Json processing while using cURL on the Terminal:
- For Windows Terminal make sure to use double quotation when needed
- For Pretty Print Json
1.npm install -g jsontool
2. use the pipe <| json> at the end of curl request on the terminal
OR
1. Download JQ
2. Rename jq-win64.exe to jq.exe
3. Place jq.exe inC:\Windows\System32
4. use the pipe <| jq> at the end of curl request on the terminal
Didn't find information needed?
Join our Scramjet Community on Discord, where you can get help from our engineers directly.