Skip to main content
API docs by Redocly

Signaloid Cloud Compute Engine API (1.1.0)

Download OpenAPI specification:Download

Signaloid Developer Support: developer-support@signaloid.com Terms of Service

This is the Signaloid Cloud Compute Engine API OpenAPI specification. Signaloid provides a computing platform to quantify, transmit, and track data uncertainty dynamically and throughout computations in unmodified computing workloads. The Signaloid Cloud Compute Engine API enables you to interface with the Signaloid Cloud Compute Engine programmatically.

Authentication

The Signaloid Cloud Compute Engine API currently offers authentication using API keys. Authentication is required for all API requests and the request must include the API key in the Authorization header. Read more about how to obtain an API key in the Authentication guide.

API Versioning

The Signaloid Cloud Compute Engine API is in beta. We make every effort to maintain backwards compatibility, but we reserve the right to make breaking changes to the API while still in beta. We will announce breaking changes in the Signaloid Cloud Platform Release Notes.

API Guides

The current page is the API reference. For more information about how to use the Signaloid Cloud API in your application and combine different requests, see the API Guides.

Buckets

List connected Buckets

Authorizations:
ApiKeybearerAuth

Responses

Response samples

Content type
application/json
{
  • "bucket_count": 0,
  • "bucket_ids": [ ],
  • "user_id": "usr_000000000000000000000000000000ab"
}

Connect a Bucket

Connect a blob storage bucket from a third-party creating a Bucket resource. Currently supports Amazon S3 buckets.

Authorizations:
ApiKeybearerAuth
Request Body schema: application/json
required
Name
required
string
Account
required
string
MountPath
string
Default: "/"

Where the bucket is mounted inside the execution environment. Defaults to /. An empty string is also stored as /.

Read
boolean
Default: true

Whether the bucket is readable from the execution environment. Defaults to true.

Write
boolean
Default: false

Whether the bucket is writable from the execution environment. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "Name": "string",
  • "Account": "string",
  • "MountPath": "/",
  • "Read": true,
  • "Write": false
}

Response samples

Content type
application/json
{
  • "Object": "Bucket",
  • "BucketID": "string",
  • "Owner": "string",
  • "CreatedAt": 0,
  • "UpdatedAt": 0,
  • "Name": "string",
  • "Account": "string",
  • "MountPath": "string",
  • "Read": true,
  • "Write": true
}

Get Bucket

Authorizations:
ApiKeybearerAuth
path Parameters
bucketID
required
string (bucketID) bkt_[a-z0-9]{32}

The identifier of the Bucket resource.

Responses

Response samples

Content type
application/json
{
  • "Object": "Bucket",
  • "BucketID": "string",
  • "Owner": "string",
  • "CreatedAt": 0,
  • "UpdatedAt": 0,
  • "Name": "string",
  • "Account": "string",
  • "MountPath": "string",
  • "Read": true,
  • "Write": true
}

Update Bucket

Authorizations:
ApiKeybearerAuth
path Parameters
bucketID
required
string (bucketID) bkt_[a-z0-9]{32}

The identifier of the Bucket resource.

Request Body schema: application/json
required
non-empty
Name
string
Account
string
MountPath
string
Read
boolean
Write
boolean

Responses

Request samples

Content type
application/json
{
  • "Name": "string",
  • "Account": "string",
  • "MountPath": "string",
  • "Read": true,
  • "Write": true
}

Response samples

Content type
application/json
{
  • "Object": "Bucket",
  • "BucketID": "string",
  • "Owner": "string",
  • "CreatedAt": 0,
  • "UpdatedAt": 0,
  • "Name": "string",
  • "Account": "string",
  • "MountPath": "string",
  • "Read": true,
  • "Write": true
}

Delete Bucket

Authorizations:
ApiKeybearerAuth
path Parameters
bucketID
required
string (bucketID) bkt_[a-z0-9]{32}

The identifier of the Bucket resource.

Responses

Response samples

Content type
application/json
{
  • "error": "Bad Request",
  • "message": "Missing or malformed 'Name' field"
}

Builds

Create Build from Repository

Creates a new build from the specified repository.

Authorizations:
ApiKeybearerAuth
path Parameters
RepositoryID
required
string (RepositoryID) rep_[a-z0-9]{32}

The identifier of the connected Repository resource.

query Parameters
DiscoverVariables
string
Default: "false"
Enum: "true" "false"

If set to the string "true", the build will attempt to discover variables that can be traced. The comparison is exact and case-sensitive: any other value — including "TRUE" and "1" — is treated as "false".

Request Body schema: application/json
CoreID
stringcor_[a-z0-9]{32}

The Core to build for. Defaults to the Repository's Core field.

Array of objects (TraceVariableRequest)

Variables to trace in the built application. Defaults to the Repository's TraceVariables, or to an empty list if the Repository does not define any.

Array
File
required
string
LineNumber
required
integer >= 0
Expression
required
string

The expression to trace. E.g., x[0]. To learn more about tracing expressions, see the Tracing Variables section in the API Guides.

Array of objects (DataSource) [ 0 .. 5 ] items

Data sources to use with this build. Defaults to the Repository's DataSources, or to an empty list if the Repository does not define any. Must be empty for the C0-microSD and C0-microSD-plus Core classes, which otherwise return 403 Forbidden.

Array ([ 0 .. 5 ] items)
Object
required
string
Value: "DataSource"
Location
required
string
ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "Gateway" "Bucket" "Drive" "SignaloidCloudStorage"
Arguments
string

Command-line arguments to pass to the application. Defaults to the Repository's Arguments, or to the empty string if the Repository does not define any.

IsPublic
boolean
Default: false

Marks the build as publicly accessible. When enabled, other users can run tasks based on this build without requiring authorization. Only the literal value true enables this; any other value, and omitting the field, leaves the build private.

Responses

Request samples

Content type
application/json
{
  • "CoreID": "string",
  • "TraceVariables": [
    ],
  • "DataSources": [
    ],
  • "Arguments": "string",
  • "IsPublic": false
}

Response samples

Content type
application/json
{
  • "BuildID": "string"
}

List Builds

Returns the list of builds.

Authorizations:
ApiKeybearerAuth
query Parameters
startKey
string

Where to resume the list of Builds. Use for paginating responses. Pass back the ContinuationKey returned by the previous response. The value is of the form <CreatedAt>#<BuildID>, where <CreatedAt> is an ISO 8601 UTC timestamp with millisecond precision — for example 2026-01-31T12:00:00.000Z#bld_0123456789abcdef0123456789abcdef.

from
string <date-time>

Filter builds by creation date - only include builds created on or after this date.

to
string <date-time>

Filter builds by creation date - only include builds created on or before this date.

status
Array of strings (BuildStatus)
Default: ""
Items Enum: "Accepted" "Initialising" "Rescheduled" "In Progress" "Completed" "Cancelled" "Stopped"

Filter the list of builds by status. By default the list includes all Builds. Repeat the parameter to filter on more than one status, for example ?status=Completed&status=Stopped.

noexpand
string
Default: "false"
Enum: "true" "false"

By default each entry in Builds is a fully expanded Build object. Set this parameter to the string true to return unexpanded entries instead, which raises the maximum page size from 25 to 500. Any value other than true is treated as false.

limit
integer [ 1 .. 500 ]
Default: 25

The maximum number of Builds to return in one page. The effective maximum — and the value used when this parameter is omitted, is not a number, or exceeds the maximum — is 25 for expanded responses and 500 when noexpand=true.

Responses

Response samples

Content type
application/json
{
  • "UserID": "string",
  • "Builds": [
    ],
  • "Count": 0,
  • "ContinuationKey": "string"
}

Get Build

Returns the build resource identified by the BuildID path parameter.

Authorizations:
ApiKeybearerAuth
path Parameters
BuildID
required
string (BuildID) bld_[a-z0-9]{32}

The identifier of the Build resource.

Responses

Response samples

Content type
application/json
{
  • "Object": "Build",
  • "BuildID": "string",
  • "Owner": "string",
  • "Status": "Accepted",
  • "StatusTransitions": [
    ],
  • "StartedAt": 0,
  • "DefaultArguments": "string",
  • "DefaultDataSources": [
    ],
  • "Application": {
    },
  • "UpdatedAt": 0,
  • "CreatedAt": 0,
  • "FinishedAt": 0,
  • "BuildArtifactAvailable": true,
  • "IsPublic": true,
  • "BuildCoreSpecs": {
    },
  • "TraceVariables": [
    ],
  • "Stats": {
    }
}

Update Build

Updates the build resource identified by the BuildID path parameter. Currently supports updating the IsPublic field to control public accessibility of the build.

Authorizations:
ApiKeybearerAuth
path Parameters
BuildID
required
string (BuildID) bld_[a-z0-9]{32}

The identifier of the Build resource.

Request Body schema: application/json
required
IsPublic
boolean

Marks the build as publicly accessible. When enabled, other users can run tasks based on this build without requiring authorization.

Responses

Request samples

Content type
application/json
{
  • "IsPublic": true
}

Response samples

Content type
application/json
{
  • "Object": "Build",
  • "BuildID": "string",
  • "Owner": "string",
  • "Status": "Accepted",
  • "StatusTransitions": [
    ],
  • "StartedAt": 0,
  • "DefaultArguments": "string",
  • "DefaultDataSources": [
    ],
  • "Application": {
    },
  • "UpdatedAt": 0,
  • "CreatedAt": 0,
  • "FinishedAt": 0,
  • "BuildArtifactAvailable": true,
  • "IsPublic": true,
  • "BuildCoreSpecs": {
    },
  • "TraceVariables": [
    ],
  • "Stats": {
    }
}

Delete Build

Permanently deletes the build asset identified by the BuildID path parameter. This operation cannot be performed on active builds.

Authorizations:
ApiKeybearerAuth
path Parameters
BuildID
required
string (BuildID) bld_[a-z0-9]{32}

The identifier of the Build resource.

Responses

Response samples

Content type
application/json
{
  • "error": "Bad Request",
  • "message": "string"
}

Get Build Binary

Returns a pre-signed URL to download the binary artifact for the build identified by the BuildID path parameter. This is only available for builds with C0-microSD core class.

Authorizations:
ApiKeybearerAuth
path Parameters
BuildID
required
string (BuildID) bld_[a-z0-9]{32}

The identifier of the Build resource.

Responses

Response samples

Content type
application/json
{}

Get Build Outputs

Returns URLs to the output files associated with the build.

Authorizations:
ApiKeybearerAuth
path Parameters
BuildID
required
string (BuildID) bld_[a-z0-9]{32}

The identifier of the Build resource.

Responses

Response samples

Content type
application/json
{
  • "Build": "string"
}

Get Build Variables

Returns the list of variables discovered in the build.

Authorizations:
ApiKeybearerAuth
path Parameters
BuildID
required
string (BuildID) bld_[a-z0-9]{32}

The identifier of the Build resource.

query Parameters
startKey
string

The key to start from when returning the list of variables. Used for paginating responses.

Responses

Response samples

Content type
application/json
{
  • "BuildID": "string",
  • "Variables": [
    ],
  • "Count": 0,
  • "ContinuationKey": "string"
}

Cancel Build

Cancels an active build identified by the BuildID path parameter.

Authorizations:
ApiKeybearerAuth
path Parameters
BuildID
required
string (BuildID) bld_[a-z0-9]{32}

The identifier of the Build resource.

Responses

Response samples

Content type
application/json
{
  • "Message": "Cancel Build Signal sent"
}

List Build Tasks

Returns the list of tasks associated with the specified build.

Authorizations:
ApiKeybearerAuth
path Parameters
BuildID
required
string (BuildID) bld_[a-z0-9]{32}

The identifier of the Build resource.

query Parameters
startKey
string

The key to start from when returning the list of tasks. Used for paginating responses.

from
string <date-time>

Filter tasks by creation date - only include tasks created on or after this date.

to
string <date-time>

Filter tasks by creation date - only include tasks created on or before this date.

Responses

Response samples

Content type
application/json
{
  • "BuildID": "string",
  • "Tasks": [
    ],
  • "Count": 0,
  • "ContinuationKey": "string"
}

Create Task from Build

Creates a new task using the specified build.

Authorizations:
ApiKeybearerAuth
path Parameters
BuildID
required
string (BuildID) bld_[a-z0-9]{32}

The identifier of the Build resource.

Request Body schema: application/json
Arguments
string

Command-line arguments to pass to the application. Defaults to the Build's DefaultArguments, or to the empty string if the Build does not define any.

Array of objects (DataSource) [ 0 .. 5 ] items

Data sources to attach to the Task. Defaults to the Build's DefaultDataSources, or to an empty list if the Build does not define any.

Array ([ 0 .. 5 ] items)
Object
required
string
Value: "DataSource"
Location
required
string
ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "Gateway" "Bucket" "Drive" "SignaloidCloudStorage"

Responses

Request samples

Content type
application/json
{
  • "Arguments": "string",
  • "DataSources": [
    ]
}

Response samples

Content type
application/json
{
  • "TaskID": "string"
}

Create Build From Single-file Source Code

Creates a new build from a single-file source code. The source code is compiled and built using the specified core.

Authorizations:
ApiKeybearerAuth
query Parameters
DiscoverVariables
string
Default: "false"
Enum: "true" "false"

If set to the string "true", the build will attempt to discover variables that can be traced. The comparison is exact and case-sensitive: any other value — including "TRUE" and "1" — is treated as "false".

Request Body schema: application/json
required
Code
required
string

The source code to build. Can be provided as plain text or Base64 encoded.

Language
required
string
Enum: "C" "C++" "Fortran"

The programming language of the source code. Fortran is recognised but not yet supported and is rejected with 400 Bad Request.

CoreID
string

The ID of the core to use for building. If omitted, the Signaloid Cloud Platform assigns the default Core with the lowest precision that is available to your account.

Array of objects (TraceVariableRequest)
Default: []

Variables to trace in the built application. Defaults to an empty list.

Array
File
required
string
LineNumber
required
integer >= 0
Expression
required
string

The expression to trace. E.g., x[0]. To learn more about tracing expressions, see the Tracing Variables section in the API Guides.

Array of objects (DataSource) [ 0 .. 5 ] items
Default: []

Data sources to use with this build. Defaults to an empty list. Must be empty for the C0-microSD and C0-microSD-plus Core classes, which otherwise return 400 Bad Request.

Array ([ 0 .. 5 ] items)
Object
required
string
Value: "DataSource"
Location
required
string
ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "Gateway" "Bucket" "Drive" "SignaloidCloudStorage"
Arguments
string
Default: ""

Command-line arguments to pass to the compiled program at runtime. Defaults to the empty string.

IsPublic
boolean
Default: false

Marks the build as publicly accessible. When enabled, other users can run tasks based on this build without requiring authorization. Only the literal value true enables this; any other value, and omitting the field, leaves the build private.

ConfigMk
string

Contents of a config.mk file to customize the build. Can be provided as plain text or Base64-encoded. Maximum size is 64 KB after decoding.

Responses

Request samples

Content type
application/json
{
  • "Code": "string",
  • "Language": "C",
  • "CoreID": "string",
  • "TraceVariables": [ ],
  • "DataSources": [ ],
  • "Arguments": "",
  • "IsPublic": false,
  • "ConfigMk": "string"
}

Response samples

Content type
application/json
{
  • "BuildID": "string"
}

Open (authentication-free) Create Task from Build

Creates a new task from a publicly accessible build. You can use this endpoint only with builds marked as public and does not require authorization.

path Parameters
BuildID
required
string (BuildID) bld_[a-z0-9]{32}

The identifier of the Build resource.

Request Body schema: application/json
Arguments
string

Command-line arguments to pass to the application. Defaults to the Build's DefaultArguments, or to the empty string if the Build does not define any.

Array of objects (DataSource) [ 0 .. 5 ] items

Data sources to attach to the Task. Defaults to the Build's DefaultDataSources, or to an empty list if the Build does not define any.

Array ([ 0 .. 5 ] items)
Object
required
string
Value: "DataSource"
Location
required
string
ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "Gateway" "Bucket" "Drive" "SignaloidCloudStorage"

Responses

Request samples

Content type
application/json
{
  • "Arguments": "string",
  • "DataSources": [
    ]
}

Response samples

Content type
application/json
{
  • "TaskID": "string"
}

Cloud Storage

List Files or Directories

Authorizations:
ApiKeybearerAuth
query Parameters
path
string
Default: ""

Directory to list, relative to the authenticated user's storage root. Defaults to the empty string, which — like / — lists the root directory. Path traversal sequences (..) are rejected with 400 Bad Request.

startKey
string

Continuation token for paginated results. Omit on the first request; on subsequent requests pass the URL-encoded nextContinuationToken returned by the previous response. At most 100 items are returned per page.

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "items": [
    ],
  • "nextContinuationToken": "string"
}

Download a file or list a directory

Authorizations:
ApiKeybearerAuth
path Parameters
path
required
string

The relative path to the file or directory.

query Parameters
download
boolean
Default: false

If provided, returns a pre-signed download URL for the specified file instead of its metadata.

This is a presence flag: the parameter is enabled by being present, whatever its value. ?download, ?download=true and ?download=false all request a download; omit the parameter entirely to get metadata.

Responses

Response samples

Content type
application/json
Example
{
  • "count": 6,
  • "items": [
    ]
}

Upload a file or create a directory

Authorizations:
ApiKeybearerAuth
path Parameters
path
required
string

The relative path where the file or directory will be created.

query Parameters
directory
boolean
Default: false

If provided, creates a directory at the specified path instead of uploading a file.

This is a presence flag: the parameter is enabled by being present, whatever its value. ?directory, ?directory=true and ?directory=false all create a directory; omit the parameter entirely to upload a file.

size
integer [ 1 .. 5368709120 ]

The size of the file to be uploaded, in bytes. Required for file uploads: when directory is not set, omitting this parameter is equivalent to sending 0 and is rejected with 400 Bad Request. Ignored when creating a directory. The maximum is 5 GiB (5368709120 bytes), the largest single-part S3 upload.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "upload_url": "string"
}

Delete a file or directory

Authorizations:
ApiKeybearerAuth
path Parameters
path
required
string

The relative path to the file or directory to delete.

query Parameters
recursive
boolean
Default: false

If provided, deletes directories and their contents recursively. Valid only together with directory; sending recursive without directory is rejected with 400 Bad Request.

This is a presence flag: the parameter is enabled by being present, whatever its value. ?recursive, ?recursive=true and ?recursive=false all enable recursive deletion; omit the parameter entirely to disable it.

directory
boolean
Default: false

If provided, specifies that the path refers to a directory.

This is a presence flag: the parameter is enabled by being present, whatever its value. ?directory, ?directory=true and ?directory=false all mark the path as a directory; omit the parameter entirely to delete a file.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Cores

List Cores

Returns the list of custom Signaloid cores available to the account. The response does not include the default cores available to all accounts.

Authorizations:
ApiKeybearerAuth
query Parameters
default
boolean
Default: false

By default this API will return your custom cores. By providing this parameter you will get back the default cores, created and managed by Signaloid for you.

This is a presence flag: the parameter is enabled by being present, whatever its value. ?default, ?default=true and ?default=false all select the default cores; omit the parameter entirely to get your custom cores.

Responses

Response samples

Content type
application/json
{
  • "UserID": "usr_b0bf834b1ec54d6cb332cc1300efdcba",
  • "Count": 3,
  • "ContinuationKey": "cor_051481609fe04665b576ab066e378257",
  • "Cores": [
    ]
}

Create Core

Creates a new custom Signaloid Core. The new Core becomes available to the account and is returned in the response.

Authorizations:
ApiKeybearerAuth
Request Body schema: application/json
required
Name
required
string non-empty
Class
required
string
Enum: "C0" "C0Pro" "C0-microSD" "C0-microSD-plus"
Precision
required
integer [ 4 .. 1000000 ]

The precision of the core. The minimum value is 4. The maximum value is 8000 for the Athens Microarchitecture, and 1000000 (1M) for the Reference Microarchitecture.

MemorySize
required
integer [ 256000 .. 4000000000 ]
Microarchitecture
required
string (Microarchitecture)
Enum: "Athens" "Atlas" "Jupiter" "Bypass" "Reference"

The Core microarchitecture. The value is case-sensitive. Note that the Atlas microarchitecture is not supported for the C0 Core class; requesting that combination returns 400 Bad Request.

CorrelationTracking
required
string (CorrelationTracking)
Enum: "Autocorrelation" "Disable"

The value is case-sensitive.

Responses

Request samples

Content type
application/json
{
  • "Name": "My New Custom Core",
  • "Class": "C0",
  • "Microarchitecture": "Athens",
  • "CorrelationTracking": "Autocorrelation",
  • "MemorySize": 256000,
  • "Precision": 128
}

Response samples

Content type
application/json
{
  • "Object": "Core",
  • "CoreID": "cor_3ff9395ee9494f3d91a8e1b5999d737e",
  • "Owner": "usr_b0bf834b1ec54d6cb332cc1300efdcba",
  • "CreatedAt": 1677025457,
  • "UpdatedAt": 1677025457,
  • "Name": "My New Custom Core",
  • "Class": "C0",
  • "Microarchitecture": "Athens",
  • "CorrelationTracking": "Autocorrelation",
  • "MemorySize": 256000,
  • "Precision": 128
}

Get Core

Returns the custom Signaloid core identified by the CoreID path parameter.

Authorizations:
ApiKeybearerAuth
path Parameters
CoreID
required
string (CoreID) cor_[a-z0-9]{32}

The identifier of the Core resource.

query Parameters
default
boolean
Default: false

By default this API looks up a custom core owned by your account. By providing this parameter you look up a default core, created and managed by Signaloid.

This is a presence flag: the parameter is enabled by being present, whatever its value. ?default, ?default=true and ?default=false all select the default cores; omit the parameter entirely to look up your custom cores.

Responses

Response samples

Content type
application/json
{
  • "Object": "Core",
  • "CoreID": "string",
  • "Owner": "string",
  • "Name": "string",
  • "Class": "C0",
  • "Precision": 4,
  • "Microarchitecture": "Athens",
  • "MemorySize": 256000,
  • "CorrelationTracking": "Autocorrelation",
  • "CreatedAt": 0,
  • "UpdatedAt": 0
}

Delete Core

Permanently deletes the custom Signaloid core identified by the CoreID parameter.

Authorizations:
ApiKeybearerAuth
path Parameters
CoreID
required
string (CoreID) cor_[a-z0-9]{32}

The identifier of the Core resource.

Responses

Response samples

Content type
application/json
{
  • "message": "OK"
}

Update Core

Updates the custom Signaloid core identified by the CoreID parameter. This method is useful for updating the core of a specific CoreID without having to edit integrations that use this core. The request must change at least one of the editable Core properties for the Signaloid Cloud API to accept it. The response is the edited core.

Authorizations:
ApiKeybearerAuth
path Parameters
CoreID
required
string (CoreID) cor_[a-z0-9]{32}

The identifier of the Core resource.

Request Body schema: application/json
required
Name
required
string non-empty
Class
required
string
Enum: "C0" "C0Pro" "C0-microSD" "C0-microSD-plus"
Precision
required
integer [ 4 .. 1000000 ]

The precision of the core. The minimum value is 4. The maximum value is 8000 for the Athens Microarchitecture, and 1000000 (1M) for the Reference Microarchitecture.

MemorySize
required
integer [ 256000 .. 4000000000 ]
Microarchitecture
required
string (Microarchitecture)
Enum: "Athens" "Atlas" "Jupiter" "Bypass" "Reference"

The Core microarchitecture. The value is case-sensitive. Note that the Atlas microarchitecture is not supported for the C0 Core class; requesting that combination returns 400 Bad Request.

CorrelationTracking
required
string (CorrelationTracking)
Enum: "Autocorrelation" "Disable"

The value is case-sensitive.

Responses

Request samples

Content type
application/json
{
  • "Name": "string",
  • "Class": "C0",
  • "Precision": 4,
  • "MemorySize": 256000,
  • "Microarchitecture": "Athens",
  • "CorrelationTracking": "Autocorrelation"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Drives

List Drives

Authorizations:
ApiKeybearerAuth

Responses

Response samples

Content type
application/json
{
  • "drive_count": 0,
  • "drive_ids": [ ],
  • "user_id": "usr_000000000000000000000000000000ab"
}

Create a Drive

Authorizations:
ApiKeybearerAuth
Request Body schema: application/json
required
required
Array of objects (DataSources) [ 0 .. 5 ] items
Array ([ 0 .. 5 ] items)
Object
required
string
Value: "DataSource"
Location
required
string
ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "Gateway" "Bucket" "Drive" "SignaloidCloudStorage"
Name
required
string

Responses

Request samples

Content type
application/json
{
  • "DataSources": [
    ],
  • "Name": "sampleDrive"
}

Response samples

Content type
application/json
{
  • "CreatedAt": 1666947436,
  • "DataSources": [
    ],
  • "DriveID": "drv_c5ef68a00ba445ca8b191e4d24224002",
  • "Name": "sampleDrive",
  • "Object": "Drive",
  • "Owner": "usr_000000000000000000000000000000ab",
  • "UpdatedAt": 1666947436
}

Delete drive

Authorizations:
ApiKeybearerAuth
path Parameters
driveID
required
string (driveID) drv_[a-z0-9]{32}

The identifier of the Drive resource.

Responses

Response samples

Content type
application/json
{
  • "error": "Bad Request",
  • "message": "Missing or malformed 'Name' field"
}

Get Drive

Authorizations:
ApiKeybearerAuth
path Parameters
driveID
required
string (driveID) drv_[a-z0-9]{32}

The identifier of the Drive resource.

Responses

Response samples

Content type
application/json
{
  • "CreatedAt": 1666947436,
  • "DataSources": [ ],
  • "DriveID": "drv_c5ef68a00ba445ca8b191e4d24224002",
  • "Name": "sampleDrive",
  • "Object": "Drive",
  • "Owner": "usr_000000000000000000000000000000ab",
  • "UpdatedAt": 1666947455
}

Update drive

Authorizations:
ApiKeybearerAuth
path Parameters
driveID
required
string (driveID) drv_[a-z0-9]{32}

The identifier of the Drive resource.

Request Body schema: application/json
required
non-empty
Array of objects (DataSources) [ 0 .. 5 ] items
Array ([ 0 .. 5 ] items)
Object
required
string
Value: "DataSource"
Location
required
string
ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "Gateway" "Bucket" "Drive" "SignaloidCloudStorage"
Name
string

Responses

Request samples

Content type
application/json
{
  • "DataSources": [ ],
  • "Name": "sampleDrive"
}

Response samples

Content type
application/json
{
  • "error": "Bad Request",
  • "message": "Missing or malformed 'Name' field"
}

Health

Get system health status

Returns the health status of Signaloid Cloud services.

The health check system monitors:

  • Signaloid Cloud Developer Platform (SCDP)
  • Signaloid Cloud Compute Engine (SCCE) API
  • SCCE Compute Engine
  • SCCE Build Engine
Authorizations:
ApiKeybearerAuth

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2025-05-16T13:55:25.605Z",
  • "services": [
    ]
}

Keys

List API Keys

Returns the list of API keys for the authenticated user.

Authorizations:
ApiKeybearerAuth

Responses

Response samples

Content type
application/json
{
  • "UserID": "usr_000000000000000000000000000000ab",
  • "Keys": [
    ],
  • "Count": 1
}

Create API Key

Creates a new API key for the authenticated user. The full API key is only returned once upon creation and cannot be retrieved again.

Authorizations:
ApiKeybearerAuth
Request Body schema: application/json
required
Name
required
string non-empty
ValidUntil
integer or null >= 0

Responses

Request samples

Content type
application/json
{
  • "Name": "My New API Key",
  • "ValidUntil": 1735689600
}

Response samples

Content type
application/json
{
  • "Object": "Key",
  • "Key": "scce_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2_12345678",
  • "KeyID": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  • "Name": "My New API Key",
  • "Owner": "usr_000000000000000000000000000000ab",
  • "ValidUntil": 1735689600,
  • "CreatedAt": 1698241879
}

Delete API Key

Deletes an API key for the authenticated user. The key will be immediately invalidated and can no longer be used for authentication.

Authorizations:
ApiKeybearerAuth
path Parameters
KeyID
required
string^[a-f0-9]{32}$

The identifier of the API Key resource.

Responses

Response samples

Content type
application/json
{
  • "message": "OK"
}

Organizations

Create Organization

Creates a new organization. Only users with an Enterprise tier subscription can create organizations. A user may only belong to one organization.

Authorizations:
ApiKeybearerAuth
Request Body schema: application/json
required
Name
required
string

The display name of the organization.

DedicatedInstanceName
string

Optional dedicated compute instance name.

Responses

Request samples

Content type
application/json
{
  • "Name": "string",
  • "DedicatedInstanceName": "string"
}

Response samples

Content type
application/json
{
  • "OrganizationID": "string",
  • "Name": "string",
  • "Object": "Organization",
  • "Owner": "string",
  • "CreatedAt": 0,
  • "UpdatedAt": 0,
  • "DedicatedInstanceName": "string"
}

List Organization Invitations

Returns all pending organization invitations for the currently authenticated user.

Authorizations:
ApiKeybearerAuth

Responses

Response samples

Content type
application/json
{
  • "Invitations": [
    ],
  • "Count": 0
}

Get Organization

Returns the organization resource identified by the OrganizationID path parameter.

Authorizations:
ApiKeybearerAuth
path Parameters
OrganizationID
required
string

The identifier of the Organization resource.

Responses

Response samples

Content type
application/json
{
  • "OrganizationID": "string",
  • "Name": "string",
  • "Object": "Organization",
  • "Owner": "string",
  • "CreatedAt": 0,
  • "UpdatedAt": 0,
  • "DedicatedInstanceName": "string"
}

List Organization Users

Returns the list of users belonging to the specified organization.

Authorizations:
ApiKeybearerAuth
path Parameters
OrganizationID
required
string

The identifier of the Organization resource.

Responses

Response samples

Content type
application/json
{
  • "OrganizationID": "string",
  • "Users": [
    ],
  • "Count": 0
}

Add User to Organization

Invites a user to join the specified organization, sending an invitation email.

Authorizations:
ApiKeybearerAuth
path Parameters
OrganizationID
required
string

The identifier of the Organization resource.

Request Body schema: application/json
required
Email
required
string <email>

Email address of the user to invite.

Role
string
Enum: "Owner" "Member"

Role to assign to the user. Defaults to Member.

Responses

Request samples

Content type
application/json
{
  • "Email": "user@example.com",
  • "Role": "Owner"
}

Response samples

Content type
application/json
{
  • "error": "Bad Request",
  • "message": "string"
}

Update Organization User

Updates the role of a user within the specified organization.

Authorizations:
ApiKeybearerAuth
path Parameters
OrganizationID
required
string

The identifier of the Organization resource.

UserID
required
string (UserID) usr_[a-z0-9]{32}

The identifier of the User resource.

Request Body schema: application/json
required
Role
string
Enum: "Owner" "Member"

Responses

Request samples

Content type
application/json
{
  • "Role": "Owner"
}

Response samples

Content type
application/json
{
  • "error": "Bad Request",
  • "message": "string"
}

Remove User from Organization

Removes the specified user from the organization.

Authorizations:
ApiKeybearerAuth
path Parameters
OrganizationID
required
string

The identifier of the Organization resource.

UserID
required
string (UserID) usr_[a-z0-9]{32}

The identifier of the User resource.

Responses

Response samples

Content type
application/json
{
  • "error": "Bad Request",
  • "message": "string"
}

Plots

Plot Value ID

Plot a Reference Core run output value identified by the TaskID and ValueID path parameters. Returns a PlotID and a direct URL that can be used to retrieve the plot image.

Authorizations:
ApiKeybearerAuth
path Parameters
TaskID
required
string (TaskID) tsk_[a-z0-9]{32}

The identifier of the Task resource.

ValueID
required
string (valueID) val_[a-z0-9]{32}

The identifier of the Value resource.

Responses

Response samples

Content type
application/json
{}

Plot Ux String

Plot a Laplace Core run Ux string by passing into the body of the request. Returns a PlotID and a direct URL that can be used to retrieve the plot image.

Authorizations:
ApiKeybearerAuth
Request Body schema: application/json
required
payload
required
string

Responses

Request samples

Content type
application/json
{
  • "payload": "string"
}

Response samples

Content type
application/json
{}

Repositories

List connected repositories

Returns the list of git repositories available to the account.

Authorizations:
ApiKeybearerAuth
query Parameters
startKey
string (RepositoryID) rep_[a-z0-9]{32}

Where to resume the list of Repositories. Use for paginating responses. Pass back the ContinuationKey returned by the previous response.

Responses

Response samples

Content type
application/json
{
  • "UserID": "string",
  • "Repositories": [
    ],
  • "Count": 0,
  • "ContinuationKey": "string"
}

Connect a Repository

Creates a new connection to a git repository. The request must contain the URL of the repository, commit, branch, build directory, and default command-line arguments. The Arguments field is required but may be the empty string. The response is the created connected repository resource.

Authorizations:
ApiKeybearerAuth
Request Body schema: application/json
required
RemoteURL
required
string <uri>

The URL of the git repository.

Commit
required
string

The commit hash to check out.

Branch
required
string

The branch name to check out.

BuildDirectory
required
string

The directory in the repository where the Signaloid Cloud Engine should use as working directory when attempting to build the repository application. This directory is relative to the root of the repository.

Arguments
required
string or null
Default: ""

Default command-line arguments that the Signaloid Cloud Engine should pass when executing the built repository application. This field is required, but may be the empty string. If sent as null, it is stored as the empty string.

Core
stringcor_[a-z0-9]{32}

The ID of the core to use for building. If omitted, the Signaloid Cloud Platform assigns the default Core with the lowest precision that is available to your account.

Array of objects (DataSource) [ 0 .. 5 ] items
Default: []

Default data sources to use with this repository. Defaults to an empty list.

Array ([ 0 .. 5 ] items)
Object
required
string
Value: "DataSource"
Location
required
string
ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "Gateway" "Bucket" "Drive" "SignaloidCloudStorage"
Array of objects (TraceVariableRequest)
Default: []

The default variables that the Signaloid Cloud Compute Engine should trace when executing the Repository application. Defaults to an empty list.

Array
File
required
string
LineNumber
required
integer >= 0
Expression
required
string

The expression to trace. E.g., x[0]. To learn more about tracing expressions, see the Tracing Variables section in the API Guides.

Responses

Request samples

Content type
application/json
{
  • "RemoteURL": "http://example.com",
  • "Commit": "string",
  • "Branch": "string",
  • "BuildDirectory": "string",
  • "Arguments": "",
  • "Core": "string",
  • "DataSources": [ ],
  • "TraceVariables": [ ]
}

Response samples

Content type
application/json
{
  • "Object": "Repository",
  • "RepositoryID": "string",
  • "Owner": "string",
  • "RemoteURL": "http://example.com",
  • "Commit": "string",
  • "Branch": "string",
  • "BuildDirectory": "string",
  • "Arguments": "string",
  • "Core": "string",
  • "DataSources": [
    ],
  • "TraceVariables": [
    ],
  • "CreatedAt": 0,
  • "UpdatedAt": 0
}

Get Repository

Returns the connected git repository resource identified by the RepositoryID parameter.

Authorizations:
ApiKeybearerAuth
path Parameters
RepositoryID
required
string (RepositoryID) rep_[a-z0-9]{32}

The identifier of the connected Repository resource.

Responses

Response samples

Content type
application/json
{
  • "Object": "Repository",
  • "RepositoryID": "string",
  • "Owner": "string",
  • "RemoteURL": "http://example.com",
  • "Commit": "string",
  • "Branch": "string",
  • "BuildDirectory": "string",
  • "Arguments": "string",
  • "Core": "string",
  • "DataSources": [
    ],
  • "TraceVariables": [
    ],
  • "CreatedAt": 0,
  • "UpdatedAt": 0
}

Delete Repository

Permanently deletes the connected git repository resource identified by the RepositoryID parameter.

Authorizations:
ApiKeybearerAuth
path Parameters
RepositoryID
required
string (RepositoryID) rep_[a-z0-9]{32}

The identifier of the connected Repository resource.

Responses

Response samples

Content type
application/json
{
  • "message": "OK"
}

Update Repository

Updates the connected git repository resource identified by the RepositoryID parameter. This method is useful for updating the connected repository resource of a specific RepositoryID (e.g., to change the branch it points at) without having to edit integrations that use this repository. The request must change at least one of the editable repository properties for the Signaloid Cloud API to accept it. The response is the edited repository resource.

Authorizations:
ApiKeybearerAuth
path Parameters
RepositoryID
required
string (RepositoryID) rep_[a-z0-9]{32}

The identifier of the connected Repository resource.

Request Body schema: application/json
required
RemoteURL
string <uri>
Commit
string
Branch
string
BuildDirectory
string

The directory in the repository where the Signaloid Cloud Engine should use as working directory when attempting to build the repository application. This directory is relative to the root of the repository.

Arguments
string

Default command-line arguments that the Signaloid Cloud Engine should pass when executing the built repository application.

Core
string (CoreID) cor_[a-z0-9]{32}
Array of objects (DataSources) [ 0 .. 5 ] items
Array ([ 0 .. 5 ] items)
Object
required
string
Value: "DataSource"
Location
required
string
ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "Gateway" "Bucket" "Drive" "SignaloidCloudStorage"
Array of objects (TraceVariableRequest)

The default variables that the Signaloid Cloud Compute Engine should trace when executing the Repository application.

Array
File
required
string
LineNumber
required
integer >= 0
Expression
required
string

The expression to trace. E.g., x[0]. To learn more about tracing expressions, see the Tracing Variables section in the API Guides.

Responses

Request samples

Content type
application/json
{
  • "RemoteURL": "http://example.com",
  • "Commit": "string",
  • "Branch": "string",
  • "BuildDirectory": "string",
  • "Arguments": "string",
  • "Core": "string",
  • "DataSources": [
    ],
  • "TraceVariables": [
    ]
}

Response samples

Content type
application/json
{
  • "Object": "Repository",
  • "RepositoryID": "string",
  • "Owner": "string",
  • "RemoteURL": "http://example.com",
  • "Commit": "string",
  • "Branch": "string",
  • "BuildDirectory": "string",
  • "Arguments": "string",
  • "Core": "string",
  • "DataSources": [
    ],
  • "TraceVariables": [
    ],
  • "CreatedAt": 0,
  • "UpdatedAt": 0
}

List Builds for a Repository

Returns the list of Builds created from the Repository identified by the RepositoryID path parameter. The list is sorted by field CreatedAt in descending order and is limited to 25 Builds per page.

Authorizations:
ApiKeybearerAuth
path Parameters
RepositoryID
required
string (RepositoryID) rep_[a-z0-9]{32}

The identifier of the connected Repository resource.

query Parameters
startKey
string

Where to resume the list of Builds. Use for paginating responses. Pass back the ContinuationKey returned by the previous response.

from
string <date-time>

Filter Builds by creation date - only include Builds created on or after this date.

to
string <date-time>

Filter Builds by creation date - only include Builds created on or before this date.

Responses

Response samples

Content type
application/json
{
  • "RepositoryID": "string",
  • "Builds": [
    ],
  • "Count": 0,
  • "ContinuationKey": "string"
}

Create Build from Repository

Creates a new build from the specified repository.

Authorizations:
ApiKeybearerAuth
path Parameters
RepositoryID
required
string (RepositoryID) rep_[a-z0-9]{32}

The identifier of the connected Repository resource.

query Parameters
DiscoverVariables
string
Default: "false"
Enum: "true" "false"

If set to the string "true", the build will attempt to discover variables that can be traced. The comparison is exact and case-sensitive: any other value — including "TRUE" and "1" — is treated as "false".

Request Body schema: application/json
CoreID
stringcor_[a-z0-9]{32}

The Core to build for. Defaults to the Repository's Core field.

Array of objects (TraceVariableRequest)

Variables to trace in the built application. Defaults to the Repository's TraceVariables, or to an empty list if the Repository does not define any.

Array
File
required
string
LineNumber
required
integer >= 0
Expression
required
string

The expression to trace. E.g., x[0]. To learn more about tracing expressions, see the Tracing Variables section in the API Guides.

Array of objects (DataSource) [ 0 .. 5 ] items

Data sources to use with this build. Defaults to the Repository's DataSources, or to an empty list if the Repository does not define any. Must be empty for the C0-microSD and C0-microSD-plus Core classes, which otherwise return 403 Forbidden.

Array ([ 0 .. 5 ] items)
Object
required
string
Value: "DataSource"
Location
required
string
ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "Gateway" "Bucket" "Drive" "SignaloidCloudStorage"
Arguments
string

Command-line arguments to pass to the application. Defaults to the Repository's Arguments, or to the empty string if the Repository does not define any.

IsPublic
boolean
Default: false

Marks the build as publicly accessible. When enabled, other users can run tasks based on this build without requiring authorization. Only the literal value true enables this; any other value, and omitting the field, leaves the build private.

Responses

Request samples

Content type
application/json
{
  • "CoreID": "string",
  • "TraceVariables": [
    ],
  • "DataSources": [
    ],
  • "Arguments": "string",
  • "IsPublic": false
}

Response samples

Content type
application/json
{
  • "BuildID": "string"
}

Lookup Repository

Looks up a connected repository by its remote URL and branch. Returns the RepositoryID if a matching connected repository is found.

Authorizations:
ApiKeybearerAuth
query Parameters
remoteURL
required
string

The remote URL of the repository (e.g., https://github.com/owner/repo.git).

branch
required
string

The branch name to look up.

Responses

Response samples

Content type
application/json
{
  • "RepositoryID": "string"
}

Samples

List of generated samples in Reference Core runs

Returns the list of samples that were generated for the provided ValueID during the Reference Core task with the provided TaskID. In Reference Core Tasks, the Value identifiers (ValueID) are part of the standard output streams.

Authorizations:
ApiKeybearerAuth
path Parameters
TaskID
required
string (TaskID) tsk_[a-z0-9]{32}

The identifier of the Task resource.

ValueID
required
string (valueID) val_[a-z0-9]{32}

The identifier of the Value resource.

query Parameters
count
integer [ 0 .. 100000 ]
Default: 10000

By default this API will return up to 10000 samples. By providing this parameter you can specify the number of samples returned. This parameter has a maximum limit of 100000.

continuationToken
string

Opaque pagination token. Omit on the first request; on subsequent requests pass the ContinuationToken value returned by the previous response to continue from where it left off. An unparseable token is treated as if it were absent, and reading restarts from the first sample.

Responses

Response samples

Content type
application/json
{
  • "Samples": [
    ],
  • "Count": 32
}

Random samples from hexadecimal ("Ux") data

Returns a list of random samples from the provided Hexadecimal ("Ux") Data Format (Ux string). In non-Reference Core Tasks, distributions encoded as Ux strings are part of the standard output streams."

Authorizations:
ApiKeybearerAuth
query Parameters
count
integer [ 0 .. 100000 ]
Default: 10000

By default this API will return up to 10000 samples. By providing this parameter you can specify the number of samples returned. This parameter has a maximum limit of 100000.

Request Body schema: application/json
required

The request body is required on this operation. A request without a payload field is rejected with 400 Bad Request.

payload
required
string

Responses

Request samples

Content type
application/json
{
  • "payload": "string"
}

Response samples

Content type
application/json
{
  • "Samples": [
    ],
  • "Count": 32
}

Tasks

List Tasks

Returns the list of Tasks in the account. The list is sorted by field CreatedAt in descending order. To learn more about Tasks, see the Tasks section in the Signaloid Cloud Platform Documentation.

Authorizations:
ApiKeybearerAuth
query Parameters
status
Array of strings (TaskStatus)
Default: ""
Items Enum: "Accepted" "Initialising" "Rescheduled" "In Progress" "Completed" "Cancelled" "Stopped"

Filter the list of Tasks by status. By default the list includes all Tasks. Repeat the parameter to filter on more than one status, for example ?status=Completed&status=Stopped.

startKey
string^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...

Where to resume the list of Tasks. Use for paginating responses. Pass back the ContinuationKey returned by the previous response. The value must be of the form <CreatedAt>#<TaskID>, where <CreatedAt> is an ISO 8601 UTC timestamp with millisecond precision — for example 2026-01-31T12:00:00.000Z#tsk_0123456789abcdef0123456789abcdef. A value that does not match this format is rejected with 400 Bad Request.

from
string <date-time>

Filter tasks by creation date - only include tasks created on or after this date.

to
string <date-time>

Filter tasks by creation date - only include tasks created on or before this date.

noexpand
string
Default: "false"
Enum: "true" "false"

By default each entry in Tasks is a fully expanded Task object. Set this parameter to the string true to return unexpanded entries instead, which raises the maximum page size from 25 to 500. Any value other than true is treated as false.

limit
integer [ 1 .. 500 ]
Default: 25

The maximum number of Tasks to return in one page. The effective maximum — and the value used when this parameter is omitted, is not a number, or exceeds the maximum — is 25 for expanded responses and 500 when noexpand=true.

Responses

Response samples

Content type
application/json
{
  • "UserID": "string",
  • "Count": 0,
  • "ContinuationKey": "string",
  • "Tasks": [
    ]
}

Get Task

Returns the Task resource identified by the TaskID path parameter. To learn more about Tasks, see the Tasks section in the Signaloid Cloud Developer Platform Documentation.

Authorizations:
ApiKeybearerAuth
path Parameters
TaskID
required
string (TaskID) tsk_[a-z0-9]{32}

The identifier of the Task resource.

Responses

Response samples

Content type
application/json
{
  • "Object": "Task",
  • "TaskID": "string",
  • "BuildID": "string",
  • "Owner": "string",
  • "Status": "Accepted",
  • "StatusTransitions": [
    ],
  • "Arguments": "string",
  • "DataSources": [
    ],
  • "StartedAt": 0,
  • "UpdatedAt": 0,
  • "CreatedAt": 0,
  • "FinishedAt": 0,
  • "Stats": {
    }
}

Delete Task

Permanently deletes the Task identified by the TaskID path parameter. This operation cannot be performed on active tasks.

Authorizations:
ApiKeybearerAuth
path Parameters
TaskID
required
string (TaskID) tsk_[a-z0-9]{32}

The identifier of the Task resource.

Responses

Response samples

Content type
application/json
{
  • "error": "Bad Request",
  • "message": "string"
}

Open (authentication-free) Get Task

Returns the Task resource identified by the TaskID path parameter.
You can only use this authentication-free endpoint for tasks created from public builds.
To learn more about Tasks, see the Tasks section in the Signaloid Cloud Developer Platform Documentation.

Authorizations:
ApiKeybearerAuth
path Parameters
TaskID
required
string (TaskID) tsk_[a-z0-9]{32}

The identifier of the Task resource.

Responses

Response samples

Content type
application/json
{
  • "Object": "Task",
  • "TaskID": "string",
  • "BuildID": "string",
  • "Owner": "string",
  • "Status": "Accepted",
  • "StatusTransitions": [
    ],
  • "Arguments": "string",
  • "DataSources": [
    ],
  • "StartedAt": 0,
  • "UpdatedAt": 0,
  • "CreatedAt": 0,
  • "FinishedAt": 0,
  • "Stats": {
    }
}

Cancel Task

Cancels the active Task identified by the TaskID path parameter.

Authorizations:
ApiKeybearerAuth
path Parameters
TaskID
required
string (TaskID) tsk_[a-z0-9]{32}

The identifier of the Task resource.

Responses

Response samples

Content type
application/json
{
  • "Message": "Cancel Task Signal sent"
}

Get Task Outputs

Returns URLs to the output files associated with the task.

Authorizations:
ApiKeybearerAuth
path Parameters
TaskID
required
string (TaskID) tsk_[a-z0-9]{32}

The identifier of the Task resource.

Responses

Response samples

Content type
application/json
{
  • "Stdout": "string",
  • "Stderr": "string",
  • "StdoutChunks": [
    ]
}

Open (authentication-free) Get Task Outputs

Returns URLs to the output files for the specified task. This endpoint is authentication-free and you can only use it for tasks created from public builds.

path Parameters
TaskID
required
string (TaskID) tsk_[a-z0-9]{32}

The identifier of the Task resource.

Responses

Response samples

Content type
application/json
{
  • "Stdout": "string",
  • "Stderr": "string",
  • "StdoutChunks": [
    ]
}

Get Task Stream Output

Returns the requested output (Stdout or Stderr) for a specific task. Returns the plain text output, or a redirect to a download URL if output is larger than 5 MB. Optional query param to skip cache.

Authorizations:
ApiKeybearerAuth
path Parameters
TaskID
required
string

Task ID

Stream
required
string
Enum: "Stdout" "Stderr"

Output stream (Stdout or Stderr)

query Parameters
skipCache
boolean
Default: false

If true, bypass the cached copy of the output.

Responses

Response samples

Content type
"string"

Open (authentication-free) Get Task Stream Output

Returns an output stream (Stdout or Stderr) for a Task that belongs to a public Build. This endpoint is authentication-free. It returns the output as plain text, or redirects to a download URL if the output exceeds 5 MB.

Note: this operation is currently non-functional. The deployed route exposes no way to select the output stream, so every request is rejected with 400 Bad Request. Use GET /tasks/{TaskID}/outputs/public until this is resolved.

path Parameters
TaskID
required
string (TaskID) tsk_[a-z0-9]{32}

The identifier of the Task resource.

query Parameters
skipCache
boolean
Default: false

If true, bypass the cached copy of the output.

Responses

Response samples

Content type
"string"

Things

List Things

Authorizations:
ApiKeybearerAuth

Responses

Response samples

Content type
application/json
{
  • "thing_count": 1,
  • "thing_ids": [
    ],
  • "user_id": "usr_000000000000000000000000000000ab"
}

Get Thing

Authorizations:
ApiKeybearerAuth
path Parameters
thingID
required
string (thingID) thg_[a-z0-9]{32}

The identifier of the Thing resource.

Responses

Response samples

Content type
application/json
{
  • "CreatedAt": 1641031200,
  • "Name": "My Signaloid Test Thing (John Doe)",
  • "Object": "Thing",
  • "Owner": "usr_000000000000000000000000000000ab",
  • "ThingID": "thg_2cb6173b9248462d8c5c21e5e683cadc",
  • "ThingStatus": {
    },
  • "Topics": [
    ],
  • "UpdatedAt": 0
}

List Thing files

Authorizations:
ApiKeybearerAuth
path Parameters
thingID
required
string (thingID) thg_[a-z0-9]{32}

The identifier of the Thing resource.

Responses

Response samples

Content type
application/json
{
  • "items": [ ],
  • "thing_id": "thg_2cb6173b9248462d8c5c21e5e683cadc",
  • "user_id": "usr_000000000000000000000000000000ab"
}

User

Get Current User

Returns the profile of the currently authenticated user. This is a convenience endpoint that does not require knowing your own UserID.

Authorizations:
ApiKeybearerAuth

Responses

Response samples

Content type
application/json
{
  • "CreatedAt": 1642170191405,
  • "Object": "User",
  • "Preferences": {
    },
  • "ResourceUsage": {
    },
  • "UserID": "usr_000000000000000000000000000000ab",
  • "Username": "firstname.lastname@example.com"
}

Get User

Authorizations:
ApiKeybearerAuth
path Parameters
UserID
required
string (UserID) usr_[a-z0-9]{32}

The identifier of the User resource.

Responses

Response samples

Content type
application/json
{
  • "CreatedAt": 1642170191405,
  • "Object": "User",
  • "Preferences": {
    },
  • "ResourceUsage": {
    },
  • "UserID": "usr_000000000000000000000000000000ab",
  • "Username": "firstname.lastname@example.com"
}

Update User

Authorizations:
ApiKeybearerAuth
path Parameters
UserID
required
string (UserID) usr_[a-z0-9]{32}

The identifier of the User resource.

query Parameters
remove
Array of strings
Default: ""

Names of preference keys to delete. Repeat the parameter to remove more than one key, for example ?remove=Editor_Layout_VariableViewer&remove=Editor_Theme.

When this parameter is present the request body is ignored, and the operation only removes keys. A request that supplies neither a body nor this parameter is rejected with 400 Bad Request.

Request Body schema: application/json
Preferences
required
object

Responses

Request samples

Content type
application/json
{
  • "Preferences": {
    }
}

Response samples

Content type
application/json
{
  • "error": "Bad Request",
  • "message": "Missing or malformed 'Name' field"
}

Delete User

Deletes the user account identified by the UserID path parameter. This operation initiates account deletion by disabling the account, invalidating all sessions, and scheduling data cleanup.

Authorizations:
ApiKeybearerAuth
path Parameters
UserID
required
string (UserID) usr_[a-z0-9]{32}

The identifier of the User resource.

Responses

Response samples

Content type
application/json
{
  • "error": "Bad Request",
  • "message": "string"
}

Sign Out From All Devices

Signs out the user from all devices by invalidating all active sessions. This operation revokes all refresh tokens associated with the user, requiring re-authentication on all devices. Only the authenticated user can perform this action on their own account.

Authorizations:
ApiKeybearerAuth
path Parameters
UserID
required
string (UserID) usr_[a-z0-9]{32}

The identifier of the User resource.

Responses

Response samples

Content type
application/json
{
  • "message": "Successfully logged out from all sessions"
}

Get User Customization

Returns the customization settings for the specified user, including logo URL and organization membership.

Authorizations:
ApiKeybearerAuth
path Parameters
UserID
required
string (UserID) usr_[a-z0-9]{32}

The identifier of the User resource.

Responses

Response samples

Content type
application/json
{
  • "UserID": "string",
  • "Object": "Customization",
  • "LogoURL": "http://example.com",
  • "AtomicNetworks": true,
  • "Organizations": [
    ]
}

Get GitHub Integration

Returns the GitHub integration status and details for the specified user.

Authorizations:
ApiKeybearerAuth
path Parameters
UserID
required
string (UserID) usr_[a-z0-9]{32}

The identifier of the User resource.

Responses

Response samples

Content type
application/json
{
  • "UserID": "string",
  • "Object": "GitHubIntegration",
  • "GitHubLogin": "string"
}

Create or Update GitHub Integration

Creates or updates the GitHub integration for the specified user using an OAuth authorization code.

Authorizations:
ApiKeybearerAuth
path Parameters
UserID
required
string (UserID) usr_[a-z0-9]{32}

The identifier of the User resource.

Request Body schema: application/json
required
Code
required
string

GitHub OAuth authorization code.

Responses

Request samples

Content type
application/json
{
  • "Code": "string"
}

Response samples

Content type
application/json
{
  • "error": "Bad Request",
  • "message": "string"
}

Delete GitHub Integration

Removes the GitHub OAuth integration for the specified user.

Authorizations:
ApiKeybearerAuth
path Parameters
UserID
required
string (UserID) usr_[a-z0-9]{32}

The identifier of the User resource.

Responses

Response samples

Content type
application/json
{
  • "error": "Bad Request",
  • "message": "string"
}

Get User Activity Logs

Returns the activity logs for the specified user, queried from CloudWatch Logs. Logs are available only for your own account; requesting another user's logs returns 403 Forbidden.

Authorizations:
ApiKeybearerAuth
path Parameters
UserID
required
string (UserID) usr_[a-z0-9]{32}

The identifier of the User resource.

query Parameters
startTime
integer <int64>

Start of the query window, as a Unix timestamp in milliseconds. Defaults to seven days before the time of the request.

endTime
integer <int64>

End of the query window, as a Unix timestamp in milliseconds. Defaults to the time of the request.

limit
integer >= 1
Default: 100

The maximum number of log entries to return. Defaults to 100.

Responses

Response samples

Content type
application/json
{
  • "logs": [
    ]
}

GitHub API Proxy

Proxies GET requests to the GitHub API on behalf of the authenticated user, using their stored GitHub credentials.

Authorizations:
ApiKeybearerAuth
path Parameters
proxy+
required
string

The GitHub API path to proxy.

Responses

Response samples

Content type
application/json
{ }

Get Subscription

Returns the current subscription information for the authenticated user, including tier and billing period.

Authorizations:
ApiKeybearerAuth

Responses

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Update Subscription

Updates the subscription tier or billing period for the authenticated user.

Authorizations:
ApiKeybearerAuth
query Parameters
freeTrialOption
boolean
Default: false

Request the change as a free trial.

This is a presence flag: any non-empty value enables it. Omitting the parameter, or sending it empty, requests a normal subscription change.

Request Body schema: application/json
required
PriceID
string

Stripe price ID for the new subscription plan.

Responses

Request samples

Content type
application/json
{
  • "PriceID": "string"
}

Response samples

Content type
application/json
{
  • "error": "Bad Request",
  • "message": "string"
}

Webhooks

Task Status Changed Webhook

Sent when the status of a task changes. This webhook is triggered for all task status transitions.

Event Types

  • Initializing
  • In Progress
  • Completed
  • Cancelled
  • Stopped
  • Failed

Authentication

The webhook endpoint must be configured with a valid API key or JWT token.

Authorizations:
ApiKeybearerAuth
Request Body schema: application/json
required
version
required
string

Webhook payload version

eventType
required
string

Type of the event

userId
required
string^usr_[a-zA-Z0-9]{32}$

ID of the user who owns the task

timestamp
required
string <date-time>

Time when the event occurred

required
object
taskId
required
string^tsk_[a-zA-Z0-9]{32}$
status
required
string
Enum: "Initializing" "In Progress" "Completed" "Cancelled" "Stopped" "Failed"
message
string

Optional status message

updatedAt
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "version": "1.0",
  • "eventType": "task-status",
  • "userId": "usr_1234567890abcdef1234567890abcdef",
  • "timestamp": "2024-03-20T10:00:00Z",
  • "data": {
    }
}

Build Status Changed Webhook

Sent when the status of a build changes. This webhook is triggered for all build status transitions.

Event Types

  • Initializing
  • In Progress
  • Completed
  • Cancelled
  • Stopped
  • Failed

Authentication

The webhook endpoint must be configured with a valid API key or JWT token.

Authorizations:
ApiKeybearerAuth
Request Body schema: application/json
required
version
required
string

Webhook payload version

eventType
required
string

Type of the event

userId
required
string^usr_[a-zA-Z0-9]{32}$

ID of the user who owns the build

timestamp
required
string <date-time>

Time when the event occurred

required
object
buildId
required
string^bld_[a-zA-Z0-9]{32}$
status
required
string
Enum: "Initializing" "In Progress" "Completed" "Cancelled" "Stopped" "Failed"
message
string

Optional status message

updatedAt
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "version": "1.0",
  • "eventType": "build-status",
  • "userId": "usr_1234567890abcdef1234567890abcdef",
  • "timestamp": "2024-03-20T10:00:00Z",
  • "data": {
    }
}

Task Count Changed Webhook

Sent when a user's task count changes. This webhook is triggered when tasks are created or completed.

Authentication

The webhook endpoint must be configured with a valid API key or JWT token.

Authorizations:
ApiKeybearerAuth
Request Body schema: application/json
required
version
required
string

Webhook payload version

eventType
required
string

Type of the event

userId
required
string^usr_[a-zA-Z0-9]{32}$

ID of the user whose task count changed

timestamp
required
string <date-time>

Time when the event occurred

required
object
UserID
required
string^usr_[a-zA-Z0-9]{32}$
Object
required
string
required
object
IncrementTaskCount
required
integer

Number of tasks added

DecrementTaskCount
required
integer

Number of tasks completed/cancelled

Responses

Request samples

Content type
application/json
{
  • "version": "1.0",
  • "eventType": "task-count",
  • "userId": "usr_1234567890abcdef1234567890abcdef",
  • "timestamp": "2024-03-20T10:00:00Z",
  • "data": {
    }
}

Build Count Changed Webhook

Sent when a user's build count changes. This webhook is triggered when builds are created or completed.

Authentication

The webhook endpoint must be configured with a valid API key or JWT token.

Authorizations:
ApiKeybearerAuth
Request Body schema: application/json
required
version
required
string

Webhook payload version

eventType
required
string

Type of the event

userId
required
string^usr_[a-zA-Z0-9]{32}$

ID of the user whose build count changed

timestamp
required
string <date-time>

Time when the event occurred

required
object
UserID
required
string^usr_[a-zA-Z0-9]{32}$
Object
required
string
required
object
IncrementBuildCount
required
integer

Number of builds added

DecrementBuildCount
required
integer

Number of builds completed/cancelled

Responses

Request samples

Content type
application/json
{
  • "version": "1.0",
  • "eventType": "build-count",
  • "userId": "usr_1234567890abcdef1234567890abcdef",
  • "timestamp": "2024-03-20T10:00:00Z",
  • "data": {
    }
}

Task Stats Changed Webhook

Sent when a user's task stats are updated. This webhook is triggered when task execution metrics change.

Authentication

The webhook endpoint must be configured with a valid API key or JWT token.

Authorizations:
ApiKeybearerAuth
Request Body schema: application/json
required
version
required
string

Webhook payload version

eventType
required
string

Type of the event

userId
required
string^usr_[a-zA-Z0-9]{32}$

ID of the user whose task stats changed

timestamp
required
string <date-time>

Time when the event occurred

required
object
UserID
required
string^usr_[a-zA-Z0-9]{32}$
Object
required
string
required
object
TotalDynamicInstructions
required
integer

Total number of dynamic instructions executed

TotalExecutionTime
required
integer

Total execution time in milliseconds

Responses

Request samples

Content type
application/json
{
  • "version": "1.0",
  • "eventType": "task-stats",
  • "userId": "usr_1234567890abcdef1234567890abcdef",
  • "timestamp": "2024-03-20T10:00:00Z",
  • "data": {
    }
}

Build Stats Changed Webhook

Sent when a user's build stats are updated. This webhook is triggered when build metrics like size and time change.

Authentication

The webhook endpoint must be configured with a valid API key or JWT token.

Authorizations:
ApiKeybearerAuth
Request Body schema: application/json
required
version
required
string

Webhook payload version

eventType
required
string

Type of the event

userId
required
string^usr_[a-zA-Z0-9]{32}$

ID of the user whose build stats changed

timestamp
required
string <date-time>

Time when the event occurred

required
object
UserID
required
string^usr_[a-zA-Z0-9]{32}$
Object
required
string
required
object
TotalBuildSize
required
integer

Total size of builds in bytes

TotalBuildTime
required
integer

Total build time in milliseconds

Responses

Request samples

Content type
application/json
{
  • "version": "1.0",
  • "eventType": "build-stats",
  • "userId": "usr_1234567890abcdef1234567890abcdef",
  • "timestamp": "2024-03-20T10:00:00Z",
  • "data": {
    }
}

Create a new webhook

Creates a new webhook endpoint for receiving event notifications.

Available Webhook Events

The infrastructure API supports webhook notifications for the following events:

1. Task Status Changed (task-status)

Triggered when a task's status changes through any of these states:

  • Initializing - Task is being set up
  • In Progress - Task is actively running
  • Completed - Task finished successfully
  • Cancelled - Task was cancelled by user
  • Stopped - Task was stopped by system
  • Failed - Task encountered an error

Payload includes: taskId, status, message, and updatedAt.

2. Build Status Changed (build-status)

Triggered when a build's status changes through any of these states:

  • Initializing - Build is being set up
  • In Progress - Build is actively running
  • Completed - Build finished successfully
  • Cancelled - Build was cancelled by user
  • Stopped - Build was stopped by system
  • Failed - Build encountered an error

Payload includes: buildId, status, message, and updatedAt.

3. Task Count Changed (task-count)

Triggered when a user's task count changes (tasks created or completed).

Payload includes: userId, IncrementTaskCount, and DecrementTaskCount.

4. Build Count Changed (build-count)

Triggered when a user's build count changes (builds created or completed).

Payload includes: userId, IncrementBuildCount, and DecrementBuildCount.

5. Task Stats Changed (task-stats)

Triggered when a user's task execution stats are updated.

Payload includes: userId, TotalDynamicInstructions, and TotalExecutionTime.

6. Build Stats Changed (build-stats)

Triggered when a user's build stats are updated.

Payload includes: userId, TotalBuildSize, and TotalBuildTime.

Webhook Payload Structure

All webhook payloads follow this consistent structure:

{
  "version": "1.0",
  "eventType": "task-status|build-status|task-count|build-count|task-stats|build-stats",
  "userId": "usr_[32-char-alphanumeric]",
  "timestamp": "2024-03-20T10:00:00Z",
  "data": {
    // Event-specific data varies by event type
  }
}

Security

  • All webhooks include a signature header for verification
  • Webhooks support retry logic for failed deliveries
  • Rate limiting applies to webhook deliveries
Authorizations:
ApiKeybearerAuth
Request Body schema: application/json
required
url
required
string <uri>

The URL where webhook events will be sent

events
required
Array of strings
Items Enum: "task-status" "build-status" "task-stats" "build-stats" "task-count" "build-count"

List of events to subscribe to

description
string
Default: ""

Optional description of the webhook. Defaults to the empty string. A newly created webhook always starts with status set to active.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "WebhookID": "wh-1234567890abcdef1234567890abcdef",
  • "URL": "https://webhook.site/1406bd34-bd36-4e83-8341-90d0bcec5b13",
  • "Events": [
    ],
  • "Description": "Test webhook",
  • "Status": "active",
  • "Secret": "whsec_1234567890abcdef1234567890abcdef",
  • "CreatedAt": "2025-05-19T16:37:44.962Z",
  • "UpdatedAt": "2025-05-19T16:37:44.962Z",
  • "FailureCount": 0,
  • "LastDeliveryStatus": null,
  • "LastDeliveryTime": null,
  • "Object": "webhook"
}

List all webhooks

Retrieves a list of all webhooks for the authenticated user

Authorizations:
ApiKeybearerAuth

Responses

Response samples

Content type
application/json
{
  • "webhooks": [
    ],
  • "count": 4
}

Get a webhook

Retrieves details of a specific webhook.

Authorizations:
ApiKeybearerAuth
path Parameters
WebhookID
required
string

The webhook ID

Responses

Response samples

Content type
application/json
{
  • "WebhookID": "wh-1234567890abcdef1234567890abcdef",
  • "URL": "https://webhook.site/1406bd34-bd36-4e83-8341-90d0bcec5b13",
  • "Events": [
    ],
  • "Description": "Test webhook",
  • "Status": "active",
  • "Secret": "whsec_1234567890abcdef1234567890abcdef",
  • "CreatedAt": "2025-05-19T16:37:44.962Z",
  • "UpdatedAt": "2025-05-19T16:37:44.962Z",
  • "FailureCount": 0,
  • "LastDeliveryStatus": null,
  • "LastDeliveryTime": null,
  • "Object": "webhook"
}

Update a webhook

Updates the configuration of an existing webhook.

Authorizations:
ApiKeybearerAuth
path Parameters
WebhookID
required
string

The webhook ID

Request Body schema: application/json
required
url
string <uri>
events
Array of strings
Items Enum: "task-status" "build-status" "task-stats" "build-stats" "task-count" "build-count"
description
string
status
string
Enum: "active" "disabled"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "WebhookID": "wh-1234567890abcdef1234567890abcdef",
  • "URL": "https://webhook.site/1406bd34-bd36-4e83-8341-90d0bcec5b13",
  • "Events": [
    ],
  • "Description": "Test webhook",
  • "Status": "active",
  • "Secret": "whsec_1234567890abcdef1234567890abcdef",
  • "CreatedAt": "2025-05-19T16:37:44.962Z",
  • "UpdatedAt": "2025-05-19T16:37:44.962Z",
  • "FailureCount": 0,
  • "LastDeliveryStatus": null,
  • "LastDeliveryTime": null,
  • "Object": "webhook"
}

Delete a webhook

Deletes a webhook endpoint.

Authorizations:
ApiKeybearerAuth
path Parameters
WebhookID
required
string

The webhook ID

Responses

Response samples

Content type
application/json
{
  • "error": "Unauthorized",
  • "message": "Not authorized request."
}

WebSockets

WebSockets

WebSocket connections to receive real-time events. This is a WebSocket-only endpoint that supports both JWT and API Key authentication.

Available Channels

The infrastructure API supports real-time events through the following channels:

1. Build Status (build-status/{userId})

Notifies about build lifecycle state changes:

  • Accepted - Build request has been accepted
  • Initializing - Build environment is being set up
  • In Progress - Build is actively running
  • Rescheduled - Build has been rescheduled
  • Completed - Build finished successfully
  • Cancelled - Build was cancelled by user
  • Stopped - Build was stopped by system

Payload includes: buildId, status, message, and timestamp.

2. Task Status (task-status/{userId})

Notifies about task lifecycle state changes:

  • Accepted - Task request has been accepted
  • Initializing - Task environment is being set up
  • In Progress - Task is actively running
  • Rescheduled - Task has been rescheduled
  • Completed - Task finished successfully
  • Cancelled - Task was cancelled by user
  • Stopped - Task was stopped by system

Payload includes: taskId, status, message, and timestamp.

3. Build Stats (build-stats/{userId})

Provides build stats updates:

  • TotalBuildSize - Size of the build in bytes
  • TotalBuildTime - Total build time in seconds

Payload includes: buildId, TotalBuildSize, and TotalBuildTime.

4. Task Stats (task-stats/{userId})

Provides task stats updates:

  • TotalDynamicInstructions - Number of dynamic instructions executed
  • TotalExecutionTime - Total execution time in milliseconds

Payload includes: taskId, TotalDynamicInstructions, and TotalExecutionTime.

5. Build Count (build-count/{userId})

Updates about build count changes:

  • IncrementBuildCount - Number of builds added
  • DecrementBuildCount - Number of builds removed

Payload includes: userId, IncrementBuildCount, and DecrementBuildCount.

6. Task Count (task-count/{userId})

Updates about task count changes:

  • IncrementTaskCount - Number of tasks added
  • DecrementTaskCount - Number of tasks removed

Payload includes: userId, IncrementTaskCount, and DecrementTaskCount.

Channel ID Helper

Use the following helper function to extract the correct portion of IDs:

function idToChannel(signaloidUserId) {
    return id.split("_")[1];
}

Connection Protocol

  1. Connect with authorization header
  2. Send connection_init message
  3. Receive connection_ack
  4. Subscribe to channels

Authentication

The WebSocket endpoint must be configured with a valid API key or JWT token. All messages are signed for verification.

Message Structure

All WebSocket messages follow this consistent structure:

{
  "type": "connection_init|connection_ack|subscribe|subscribe_success|data|error|ka",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "channel": "builds/bld_123/status",
  "payload": {
    // Channel-specific data varies by event type
  }
}

Quick Start (Node.js)

const WebSocket = require("ws");
const { v4: uuidv4 } = require("uuid");

const HTTP_DOMAIN = "realtime.signaloid.io";
const REALTIME_ENDPOINT = "wss://realtime.signaloid.io/event/realtime";
const SIGNALOID_API_KEY = "scce_xxx";
const USER_ID = "usr_xxx";

function getBase64URLEncoded(obj) {
  return Buffer.from(JSON.stringify(obj)).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}

function getAuthProtocol() {
  const header = getBase64URLEncoded({ host: HTTP_DOMAIN, authorization: SIGNALOID_API_KEY });
  return [`header-${header}`, "aws-appsync-event-ws"];
}

function idToChannel(id) { return id.split("_")[1]; }

let ws = null; 
let ready = false;

function subscribe(channel) {
  if (!ws || !ready) return;
  ws.send(JSON.stringify({
    id: uuidv4(),
    type: "subscribe",
    channel,
    authorization: { host: HTTP_DOMAIN, authorization: SIGNALOID_API_KEY }
  }));
  console.log("Subscribed:", channel);
}

async function connect() {
  return new Promise((resolve, reject) => {
    ws = new WebSocket(REALTIME_ENDPOINT, getAuthProtocol());
    ws.on("open", () => ws.send(JSON.stringify({ type: "connection_init" })));
    ws.on("message", (buf) => {
      const msg = JSON.parse(buf.toString());
      if (msg.type === "connection_ack") {
        ready = true;
        const uid = idToChannel(USER_ID);
        subscribe(`build-status/${uid}`);
        subscribe(`task-status/${uid}`);
        subscribe(`build-stats/${uid}`);
        subscribe(`task-stats/${uid}`);
        subscribe(`build-count/${uid}`);
        subscribe(`task-count/${uid}`);
        resolve();
      }
      if (msg.type === "data") console.log("Event:", msg.payload || msg.event || msg);
    });
    ws.on("error", reject);
  });
}

(async () => { await connect(); })();
Authorizations:
bearerAuthApiKey
header Parameters
Authorization
required
string

Base64 URL encoded authorization header. Format: { "host": "realtime.signaloid.io", "authorization": "Bearer " or "scce_" }

Sec-WebSocket-Protocol
required
string

WebSocket protocol header. Must include:

  • header-{base64_encoded_auth}
  • aws-appsync-event-ws

Responses

Response samples

Content type
application/json
Example
{
  • "type": "connection_init"
}

WebSockets Public

WebSocket connections to receive real-time events.

Available Channels

The infrastructure API supports real-time events through the following channels:

Public Task Status (public-task-status/{taskId})

Notifies about task lifecycle state changes:

  • Accepted - Task request has been accepted
  • Initializing - Task environment is being set up
  • In Progress - Task is actively running
  • Rescheduled - Task has been rescheduled
  • Completed - Task finished successfully
  • Cancelled - Task was cancelled by user
  • Stopped - Task was stopped by system

Payload includes: taskId, status, message, and timestamp.

Public Build Status (public-build-status/{buildId})

Notifies about build lifecycle state changes.

Payload includes: buildId, status, message, and timestamp.

Public Task Stats (public-task-stats/{taskId})

Notifies about task execution metric updates.

Payload includes: taskId, TotalDynamicInstructions, TotalExecutionTime.

Public Build Stats (public-build-stats/{buildId})

Notifies about build metric updates.

Payload includes: buildId, TotalBuildSize, TotalBuildTime.

Public Task Count (public-task-count/{userId})

Notifies about changes to a user's running task count.

Public Build Count (public-build-count/{userId})

Notifies about changes to a user's running build count.

Channel ID Helper

Use the following helper function to extract the correct portion of IDs:

function idToChannel(signaloidUserId) {
    return id.split("_")[1];
}

Connection Protocol

  1. Connect with authorization header
  2. Send connection_init message
  3. Receive connection_ack
  4. Subscribe to channels

Message Structure

All WebSocket messages follow this consistent structure:

{
  "type": "connection_init|connection_ack|subscribe|subscribe_success|data|error|ka",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "channel": "builds/bld_123/status",
  "payload": {
    // Channel-specific data varies by event type
  }
}

Quick Start (Node.js)

const WebSocket = require("ws");
const { v4: uuidv4 } = require("uuid");

const HTTP_DOMAIN = "public.realtime.signaloid.io";
const REALTIME_ENDPOINT = "wss://public.realtime.signaloid.io/event/realtime";
const TASK_ID = "tsk_xxx";
const SIGNALOID_API_KEY = "scce_xxx";

function getBase64URLEncoded(obj) {
  return Buffer.from(JSON.stringify(obj)).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}

function getAuthProtocol() {
  const header = getBase64URLEncoded({ host: HTTP_DOMAIN, authorization: "public" });
  return [`header-${header}`, "aws-appsync-event-ws"];
}

function idToChannel(id) { return id.split("_")[1]; }

let ws = null; 
let ready = false;

function subscribe(channel) {
  if (!ws || !ready) return;
  ws.send(JSON.stringify({
    id: uuidv4(),
    type: "subscribe",
    channel,
    authorization: { host: HTTP_DOMAIN, authorization: "public" }
  }));
  console.log("Subscribed:", channel);
}

async function connect() {
  return new Promise((resolve, reject) => {
    ws = new WebSocket(REALTIME_ENDPOINT, getAuthProtocol());
    ws.on("open", () => ws.send(JSON.stringify({ type: "connection_init" })));
    ws.on("message", (buf) => {
      const msg = JSON.parse(buf.toString());
      if (msg.type === "connection_ack") {
        ready = true;
        const taskId = idToChannel(TASK_ID);
        subscribe(`task-status/${taskId}`);
        resolve();
      }
      if (msg.type === "data") console.log("Event:", msg.payload || msg.event || msg);
    });
    ws.on("error", reject);
  });
}

(async () => { await connect(); })();
Authorizations:
ApiKeybearerAuth
header Parameters
Authorization
required
string

Base64 URL encoded authorization header. Format: { "host": "public.realtime.signaloid.io", "authorization": "public" }

Sec-WebSocket-Protocol
required
string

WebSocket protocol header. Must include:

  • header-{base64_encoded_auth}
  • aws-appsync-event-ws

Responses

Response samples

Content type
application/json
Example
{
  • "type": "connection_init"
}