Skip to main content

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

  1. [ GET ] - All operations requesting data from the Scramjet Cloud Platform (SCP).
  2. [ POST ] - Creating a new Hub, Sequence, or for messaging and streaming data to a Sequence.
  3. [ PUT ] - Updating existing Sequences or Instances,
  4. [ 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:

SectionContent
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>"

info

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 underneath 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 dataStatus: 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

NameDescriptionTypeRequired
filecompressed package in tar.gz formatbinaryyes
appConfigadditional package.json config filejsonno
x-namealias name for sequenceheaderno

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 existing Sequence

Parameters

NameDescriptionTypeRequired
filecompressed package in tar.gz formatbinaryyes
appConfigadditional package.json config filejsonno
x-namealias name for sequenceheaderno
[ POST ]{API Base}/sequence/:id/start- start chosen Sequence

Parameters

NameDescriptionTypeRequired
appConfigadditional package.json config filejsonno
argsadditional arguments that instance should starts withjsonno

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

NameDescriptionTypeRequired
timeoutThe number of milliseconds before the Instance will be killed. Default: 7000ms.numberno
canCallKeepaliveIf set to true, the instance will prolong the running. Default: false.booleanno

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

NameTypeDescriptionRequired
eventNamestringName of an eventtrue
messagestringJSON formatted event payloadfalse

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's status codes 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 codeDescription
200 SuccessThe request completed successfully.
202 AcceptedThe request has been accepted for processing, but the processing has not been completed.
204 No ContentThe request completed successfully, but content is not available.
400 Bad RequestThe REST request contains parameters that are not valid or missing.
401 UnauthorizedThe caller is not authorized to perform the request.
403 ForbiddenThe caller is not authorized to complete the request.
404 Not FoundThe requested resource does not exist.
406 Not AcceptableThe request contains an unsupported content type or content encoding.
412 Invalid syntaxThe request uses an invalid regular expression in the fieldname parameter for collection types.
419 Insufficient ResourcesInsufficient RAM memory availability.
422 Unprocessable EntityError encountered when unpacking a sequence.
500 Internal Server ErrorA problem has occurred. Additional information is provided in the stack trace.

tip

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 in C:\Windows\System32
    4. use the pipe < | jq > at the end of curl request on the terminal

Was it helpful?

Didn't find information needed?

Join our Scramjet Community on Discord, where you can get help from our engineers directly.