Skip to main content
API docs by Redocly

Signaloid Cloud Compute Engine REST API (4.0.0)

Download OpenAPI specification:Download

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

This is the Signaloid Cloud Compute Engine (SCCE) REST 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 REST API enables you to interface with the Signaloid Cloud Compute Engine programmatically.

Authentication

The Signaloid Cloud Compute Engine REST 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. Each tier allows a number of API key requests per billing period. Once an API key has used them, requests with that key return 403 Forbidden until the period resets or the account is upgraded. Read more about how to obtain an API key in the Authentication guide.

API Versioning

We make every effort to maintain backwards compatibility, but we reserve the right to make breaking changes to the REST API. We will announce breaking changes in the Signaloid Cloud Platform Release Notes.

Pagination

List endpoints return one page at a time, with a Pagination object that describes it:

  • The list ends when a response has no Pagination.Links.Next. Next is then left out, never null. Do not stop on an empty or short page, as one can still have a Next.
  • To get every item, follow Pagination.Links.Next until it is absent. Request Links.Next.Href as it is, or pass Links.Next.Cursor unchanged as the cursor query parameter, with the same query parameters as before. The links carry every query parameter of the request, with the limit used. Next.Href also carries the values that SCCE chose for filters the request left out, such as the time window of the logs. They count as the request's own filters, so a request that follows Next.Href is not refused for them.
  • A page holds fewer items than limit, or none, but still has a Next, only when a filter that the list applies after reading, such as status on Tasks or Builds, leaves items out, when an item was deleted while the page was read, or when the items are too large for one response.
  • The cursor is an opaque string. Do not parse, build or change it. It is not secret. It is neither encrypted nor signed, does not expire, and grants no access.
  • A cursor works only for the listing and the user that received it, and only with the same filters as the request that returned it. The filters are the query parameters that choose the items, i.e., status, from, to, path, startTime, and endTime, on the lists that support them. Other query parameters, such as limit, may change between pages. A repeated filter counts with the value the list uses, the last one sent, except status, whose values count in any order. The cursors of the default Cores, from GET /cores?default, work for any user, as all users share that list. The API refuses with 400 Bad Request a cursor that is malformed, belongs to another user, or is the result of other filters.
  • limit sets the page size. If you leave it out or set it to zero or a negative number, the endpoint's default applies. A value above the endpoint's maximum gets the maximum. Pagination.Limit reports the value used.
  • The startKey query parameter and the ContinuationKey response field are deprecated. They are a separate cursor: pass ContinuationKey as startKey, and Next.Cursor as cursor, not interchangeable. If you use both cursor and startKey, cursor prevails. Only endpoints that used startKey will accept it for a short amount of time. The rest refuse startKey with 400 Bad Request. A startKey is a bare key, so it is not checked against the query parameters. A successful response whose page starts from startKey, as the request has startKey and no cursor, has the Deprecation header of RFC 9745.
  • The lists of API keys, webhooks, and organization invitations return 100 items per page by default, so a client that needs every item must follow Pagination.Links.Next.

Task Execution Limits

Every Task runs in an isolated sandbox with these limits:

  • Wall-clock time: 8 hours. The limit covers the run of your program only. It does not count the time the Task waits in the queue, or the time the platform spends setting up data sources and uploading outputs.
  • Memory: 8 GiB, plus up to 4 GiB of swap.

A Task that reaches a limit is stopped. Its status becomes Stopped, and the Message of that status transition starts with ErrTimeout for the time limit or ErrOutOfMemory for the memory limit. When the time limit stops a Task, SCCE uploads any outputs the Task wrote up to that point.

You cannot set a shorter time limit for a Task. To stop a Task that runs longer than you expect, cancel it with POST /tasks/{TaskID}/cancel.

API Guides

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

Buckets

List connected Buckets

Returns the Buckets of the account. This list is paginated.

Authorizations:
ApiKeybearerAuth
query Parameters
cursor
string

Where to resume the listing. Omit it on the first request. On later requests, pass Pagination.Links.Next.Cursor from the previous response, unchanged. See Pagination.

startKey
string (bucketID) bkt_[a-z0-9]{32}
Deprecated

Deprecated. Use cursor instead. Where to resume the list of Buckets. Use for paginating responses. Pass back the ContinuationKey returned by the previous response. A value that is not a well-formed ID is refused with 400 Bad Request.

limit
integer
Default: 25

The maximum number of items to return in one page. The default is 25 and the maximum 100. See Pagination.

Responses

Response samples

Content type
application/json
{}

Connect a Bucket

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

Buckets have no mount path. Where a Bucket is mounted is set by the Location of each data source that refers to it. A request that sends the removed MountPath field is refused with 400 Bad Request.

Authorizations:
ApiKeybearerAuth
Request Body schema: application/json
required
Name
required
string
Account
required
string
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",
  • "Read": true,
  • "Write": false
}

Response samples

Content type
application/json
{
  • "Object": "Bucket",
  • "BucketID": "string",
  • "Owner": "string",
  • "CreatedAt": 0,
  • "UpdatedAt": 0,
  • "Name": "string",
  • "Account": "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",
  • "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
Read
boolean
Write
boolean
Region
string

Accepted but not applied yet. The stored Bucket does not change and does not report a Region.

Responses

Request samples

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

Response samples

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

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". A build for an r7i Core cannot discover variables, so "true" returns 400 Bad Request.

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

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

Using a default CoreID of the retired C0 Core class returns 400 Bad Request. The response message suggests the equivalent C0Pro default Core to use instead.

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.

A build for an r7i Core cannot trace variables. A non-empty list in the request returns 400 Bad Request, and the build ignores the Repository's TraceVariables.

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, C0-microSD-plus, and C0-SD Core classes, which otherwise return 403 Forbidden.

Array ([ 0 .. 5 ] items)
Object
required
string
Value: "DataSource"
Location
required
string

Mount location. The application opens the files of the data source under this path. Use a relative path, such as sd0/, which the application opens as sd0/.... The empty string mounts the data source at the root of the application's directory.

For security reasons, the path must stay inside the application's directory. An absolute path, or one that leaves the directory through .., returns 400 Bad Request. Creating a Task checks the data sources it inherits from its Build as well as the ones in the request.

ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "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 sets a build as public. Any other value, or 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, sorted by field CreatedAt in descending order.

This list is paginated.

Authorizations:
ApiKeybearerAuth
query Parameters
cursor
string

Where to resume the listing. Omit it on the first request. On later requests, pass Pagination.Links.Next.Cursor from the previous response, unchanged. See Pagination.

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

Deprecated. Use cursor instead. 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. Unexpanded listings never get the busy-database 503.

limit
integer [ 1 .. 500 ]
Default: 25

The maximum number of Builds to return in one page. The default and the maximum are 25 for expanded responses and 500 when noexpand=true. See Pagination.

Responses

Response samples

Content type
application/json
{
  • "UserID": "string",
  • "Builds": [
    ],
  • "Count": 0,
  • "Pagination": {
    },
  • "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 whose Core class is one of the SD-card classes C0-microSD, C0-microSD-plus, and C0-SD. A build on any other class returns 400 Bad Request.

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. This list is paginated.

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

The identifier of the Build resource.

query Parameters
cursor
string

Where to resume the listing. Omit it on the first request. On later requests, pass Pagination.Links.Next.Cursor from the previous response, unchanged. See Pagination.

startKey
string <= 1014 characters
Deprecated

Deprecated. Use cursor instead. The key to start from when returning the list of variables. Pass back the ContinuationKey returned by the previous response. At most 1,014 bytes in UTF-8. The maxLength below counts characters, so it holds only for ASCII.

limit
integer
Default: 100

The maximum number of items to return in one page. The default and the maximum are 100. See Pagination.

Responses

Response samples

Content type
application/json
{
  • "BuildID": "string",
  • "Variables": [
    ],
  • "Count": 0,
  • "Pagination": {
    },
  • "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, sorted by field CreatedAt in descending order.

This list is paginated.

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

The identifier of the Build resource.

query Parameters
cursor
string

Where to resume the listing. Omit it on the first request. On later requests, pass Pagination.Links.Next.Cursor from the previous response, unchanged. See Pagination.

startKey
string^#TASK#CREATED#[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-...
Deprecated

Deprecated. Use cursor instead. The key to start from when returning the list of tasks. Pass back the ContinuationKey returned by the previous response.

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.

limit
integer
Default: 25

The maximum number of items to return in one page. The default is 25 and the maximum 100. See Pagination.

Responses

Response samples

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

Create Task from Build

Creates a new task using the specified build.

The Signaloid Cloud Compute Engine cannot run builds of the C0-microSD, C0-microSD-plus and C0-SD Core classes, so a Task on one of them returns 400 Bad Request. Run the build on the matching Signaloid Compute Module instead. Download the binary with GET /builds/{BuildID}/binary.

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

Mount location. The application opens the files of the data source under this path. Use a relative path, such as sd0/, which the application opens as sd0/.... The empty string mounts the data source at the root of the application's directory.

For security reasons, the path must stay inside the application's directory. An absolute path, or one that leaves the directory through .., returns 400 Bad Request. Creating a Task checks the data sources it inherits from its Build as well as the ones in the request.

ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "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". A build for an r7i Core cannot discover variables, so "true" returns 400 Bad Request.

Request Body schema: application/json
required
Code
required
string non-empty

The source code to build. Can be provided as plain text or Base64 encoded. Must be a non-empty, non-whitespace string. An empty or whitespace-only value is rejected with 400 Bad Request.

A source code Build can be at most 384 KB, counting everything stored with it. That is the decoded source code and ConfigMk, plus DataSources, TraceVariables, Arguments and the Core. A larger Build is refused with 413 Payload Too Large. Build larger sources from a connected Repository instead.

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

The programming language of the source code. Fortran is recognized 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 lowest-precision C0Pro default Core available to your account.

Using a default CoreID of the retired C0 Core class returns 400 Bad Request. The response message suggests the equivalent C0Pro default Core to use instead.

Array of objects (TraceVariableRequest)
Default: []

Variables to trace in the built application. Defaults to an empty list. A build for an r7i Core cannot trace variables, so a non-empty list returns 400 Bad Request.

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, C0-microSD-plus, and C0-SD Core classes, which otherwise return 400 Bad Request.

Array ([ 0 .. 5 ] items)
Object
required
string
Value: "DataSource"
Location
required
string

Mount location. The application opens the files of the data source under this path. Use a relative path, such as sd0/, which the application opens as sd0/.... The empty string mounts the data source at the root of the application's directory.

For security reasons, the path must stay inside the application's directory. An absolute path, or one that leaves the directory through .., returns 400 Bad Request. Creating a Task checks the data sources it inherits from its Build as well as the ones in the request.

ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "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 makes the build publicly accessible. 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.

The Signaloid Cloud Compute Engine cannot run builds of the C0-microSD, C0-microSD-plus and C0-SD Core classes, so a Task on one of them returns 400 Bad Request. Run the build on the matching Signaloid Compute Module instead.

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

Mount location. The application opens the files of the data source under this path. Use a relative path, such as sd0/, which the application opens as sd0/.... The empty string mounts the data source at the root of the application's directory.

For security reasons, the path must stay inside the application's directory. An absolute path, or one that leaves the directory through .., returns 400 Bad Request. Creating a Task checks the data sources it inherits from its Build as well as the ones in the request.

ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "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

Returns the files and directories in the user's storage. This list is paginated.

Authorizations:
ApiKeybearerAuth
query Parameters
path
string
Default: ""

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

The listing is recursive. It includes the contents of every subdirectory and the entry of the listed directory itself, whose Path ends with / and whose Size is 0. Listing a directory that does not exist returns 200 OK with an empty Files list.

cursor
string

Where to resume the listing. Omit it on the first request. On later requests, pass Pagination.Links.Next.Cursor from the previous response, unchanged. See Pagination.

startKey
string
Deprecated

Deprecated. Use cursor instead. Continuation token for paginated results. Omit on the first request. On subsequent requests pass the URL-encoded ContinuationKey returned by the previous response.

limit
integer
Default: 100

The maximum number of items to return in one page. The default and the maximum are 100. See Pagination.

Responses

Response samples

Content type
application/json
{
  • "Count": 6,
  • "Files": [
    ],
  • "Pagination": {}
}

Get file metadata or a download URL

Returns the metadata of a file, or, with download, a pre-signed download URL for it. The endpoint does not list directories. A directory path returns 404 Not Found. List directories with GET /files.

Authorizations:
ApiKeybearerAuth
path Parameters
path
required
string

The relative path to the file or directory.

query Parameters
download
boolean
Default: false

If provided, the response also includes DownloadURL, a pre-signed download URL for the file, alongside its metadata.

This is a presence flag and all values, i.e., ?download, ?download=true, or ?download=false request a download. Omit the parameter entirely to get metadata.

Responses

Response samples

Content type
application/json
{}

Upload a file or create a directory

Creates a directory, or returns a URL to upload a file to.

Directory: with the directory query parameter, the API creates the directory at path and returns 200 with no UploadURL.

File: without directory, the request does not upload the file content. Upload it in two steps:

  1. Send this request with size set to the exact size of the file in bytes. The API checks that your storage usage plus size stays within your tier's limit, and returns 403 Forbidden if it does not. Otherwise it returns 200 with an UploadURL.
  2. Upload the file content with an HTTP PUT to UploadURL. The body must be exactly size bytes, because the URL is signed for that length. Do not add an Authorization header. The URL expires 15 minutes after the API creates it.

Uploading a file using the path of an existing file, replaces it.

Authorizations:
ApiKeybearerAuth
path Parameters
path
required
string

The relative path where the file or directory will be created. The parent directories do not need to exist.

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 and all values, i.e., ?directory, ?directory=true, or ?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
{}

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 and all values, i.e., ?recursive, ?recursive=true, or ?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 and all values, i.e., ?directory, ?directory=true, or ?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.

This list is paginated.

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.

The default cores your tier cannot use are left out, so on the Free tier the Mercury and Europa default cores are not listed, and a page of default cores can be short or empty. Your custom cores are always all listed. See Pagination.

cursor
string

Where to resume the listing. Omit it on the first request. On later requests, pass Pagination.Links.Next.Cursor from the previous response, unchanged. See Pagination.

startKey
string (CoreID) cor_[a-z0-9]{32}
Deprecated

Deprecated. Use cursor instead. Where to resume the list of Cores. Pass back the ContinuationKey returned by the previous response.

limit
integer
Default: 100

The maximum number of items to return in one page. The default and the maximum are 100. See Pagination.

Responses

Response samples

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

Create Core

Creates a new custom Signaloid Core. The response contains its Core ID and properties.

A request whose Precision exceeds your tier's limits is refused with 403 Forbidden when some higher tier does support the value, and with 400 Bad Request when no tier does. You can find your tier limits in the Allowance object of GET /users/{UserID} and find the per-tier limits using GET /tiers.

The Signaloid Cloud Platform assigns MemorySize from the Core class. The request may include it, but the API ignores the value.

An r7i Core needs only Name, Class and Microarchitecture, which is Native. The API sets its Precision to 0 and its DependencyTracking to None. A Bypass Core needs no Precision or DependencyTracking either. The API sets them to 0 and None.

The API returns 400 Bad Request for the retired C0 Core class.

Authorizations:
ApiKeybearerAuth
Request Body schema: application/json
required
One of
Microarchitecture
required
string
Enum: "Athens" "Rome" "Jupiter" "Mercury" "Europa" "Bypass" "Reference" "Native"

The Core microarchitecture. The value is case-sensitive.

Not every microarchitecture is available for every Core class:

  • C0Pro supports Athens, Rome, Jupiter, Mercury, Europa, Bypass and Reference.
  • C0-microSD, C0-microSD-plus and C0-SD support Athens, Rome and Bypass.
  • r7i supports Native only, which runs the application without arithmetic on distributions.

Native is valid with no class other than r7i. Requesting an unsupported combination returns 400 Bad Request.

Each microarchitecture accepts only some DependencyTracking values. See #/DependencyTracking.

Athens, Rome, Jupiter, Mercury and Europa are the distribution-tracking microarchitectures. Their Precision is chosen by the caller, must be a power of two, and is capped by the tier's CorePrecisionBits. Mercury and Europa accept the same inputs as Jupiter.

Rome was formerly named Atlas. Existing Atlas Cores now read back as Rome, and the API refuses Atlas in requests.

Which of these your account may actually use is a separate, tier-level restriction. The list for your own account is returned as Microarchitectures by GET /users/{UserID}, and per tier as CoreAvailableMicroarchitectures by GET /tiers. The Free tier does not provide Mercury or Europa. Creating such a Core, building with one, or setting one as a Repository's Core on the Free tier returns 403 Forbidden, and GET /cores?default leaves such Cores out.

Precision
integer [ 0 .. 10000000 ]

Required for every class except r7i, unless the Microarchitecture is Bypass. Both always have 0. See #/Precision.

Name
required
string non-empty
Class
required
string
Enum: "C0Pro" "r7i" "C0-microSD" "C0-microSD-plus" "C0-SD"

The Core class. The value is case-sensitive.

  • C0Pro: Runs in the Signaloid Cloud Compute Engine with distribution arithmetic.
  • r7i: Builds with an unmodified gcc toolchain and runs in the Signaloid Cloud Compute Engine without distribution arithmetic. Its Precision is always 0 and its DependencyTracking is always None, so you may omit both. Builds for an r7i Core cannot discover or trace variables, and their Tasks produce no Ux values.
  • C0-microSD, C0-microSD-plus, C0-SD: Build for the matching Signaloid Compute Module. Download the binary with GET /builds/{BuildID}/binary. The API refuses Tasks on these builds.

The C0 class has been retired. Sending it returns 400 Bad Request with a message naming C0Pro as its replacement, which accepts the same Precision and Microarchitecture values. Existing C0 Cores are migrated by a single PATCH /cores/{CoreID} setting Class to C0Pro.

Which classes your account may use is tier-gated, except r7i, which every tier may use. The ones available to you, with the microarchitectures each supports, are returned as CoreClasses by GET /users/{UserID}.

MemorySize
integer >= 0
Deprecated

Accepted and ignored. The Signaloid Cloud Platform assigns the memory size from the Core class, and responses report that value.

DependencyTracking
string
Enum: "None" "Basic" "Advanced"

Required for every class except r7i, unless the Microarchitecture is Bypass. Both always have None. See #/DependencyTracking.

Responses

Request samples

Content type
application/json
Example
{
  • "Name": "My New Custom Core",
  • "Class": "C0Pro",
  • "Microarchitecture": "Athens",
  • "DependencyTracking": "Basic",
  • "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": "C0Pro",
  • "Microarchitecture": "Athens",
  • "DependencyTracking": "Basic",
  • "MemorySize": 8589934592,
  • "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
Example
{
  • "Microarchitecture": "Athens",
  • "Precision": 10000000,
  • "Object": "Core",
  • "CoreID": "string",
  • "Owner": "string",
  • "Name": "string",
  • "Class": "C0",
  • "MemorySize": 0,
  • "DependencyTracking": "None",
  • "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. The request must update at least one of the editable Core properties for the Signaloid Cloud API to accept it. The response contains the properties of the updated core.

A request whose Precision exceeds your tier's limits is refused with 403 Forbidden when some higher tier does support the value, and with 400 Bad Request when no tier does. You can find your tier limits in the Allowance object of GET /users/{UserID} and find the per-tier limits using GET /tiers.

The Signaloid Cloud Platform assigns MemorySize from the Core class. The request may include it, but the API ignores the value.

An r7i Core needs only Name, Class and Microarchitecture, which is Native. The API sets its Precision to 0 and its DependencyTracking to None. A Bypass Core needs no Precision or DependencyTracking either. The API sets them to 0 and None.

The API returns 400 Bad Request for the retired C0 Core class.

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
One of
Microarchitecture
required
string
Enum: "Athens" "Rome" "Jupiter" "Mercury" "Europa" "Bypass" "Reference" "Native"

The Core microarchitecture. The value is case-sensitive.

Not every microarchitecture is available for every Core class:

  • C0Pro supports Athens, Rome, Jupiter, Mercury, Europa, Bypass and Reference.
  • C0-microSD, C0-microSD-plus and C0-SD support Athens, Rome and Bypass.
  • r7i supports Native only, which runs the application without arithmetic on distributions.

Native is valid with no class other than r7i. Requesting an unsupported combination returns 400 Bad Request.

Each microarchitecture accepts only some DependencyTracking values. See #/DependencyTracking.

Athens, Rome, Jupiter, Mercury and Europa are the distribution-tracking microarchitectures. Their Precision is chosen by the caller, must be a power of two, and is capped by the tier's CorePrecisionBits. Mercury and Europa accept the same inputs as Jupiter.

Rome was formerly named Atlas. Existing Atlas Cores now read back as Rome, and the API refuses Atlas in requests.

Which of these your account may actually use is a separate, tier-level restriction. The list for your own account is returned as Microarchitectures by GET /users/{UserID}, and per tier as CoreAvailableMicroarchitectures by GET /tiers. The Free tier does not provide Mercury or Europa. Creating such a Core, building with one, or setting one as a Repository's Core on the Free tier returns 403 Forbidden, and GET /cores?default leaves such Cores out.

Precision
integer [ 0 .. 10000000 ]

Required for every class except r7i, unless the Microarchitecture is Bypass. Both always have 0. See #/Precision.

Name
required
string non-empty
Class
required
string
Enum: "C0Pro" "r7i" "C0-microSD" "C0-microSD-plus" "C0-SD"

The Core class. The value is case-sensitive.

  • C0Pro: Runs in the Signaloid Cloud Compute Engine with distribution arithmetic.
  • r7i: Builds with an unmodified gcc toolchain and runs in the Signaloid Cloud Compute Engine without distribution arithmetic. Its Precision is always 0 and its DependencyTracking is always None, so you may omit both. Builds for an r7i Core cannot discover or trace variables, and their Tasks produce no Ux values.
  • C0-microSD, C0-microSD-plus, C0-SD: Build for the matching Signaloid Compute Module. Download the binary with GET /builds/{BuildID}/binary. The API refuses Tasks on these builds.

The C0 class has been retired. Sending it returns 400 Bad Request with a message naming C0Pro as its replacement, which accepts the same Precision and Microarchitecture values. Existing C0 Cores are migrated by a single PATCH /cores/{CoreID} setting Class to C0Pro.

Which classes your account may use is tier-gated, except r7i, which every tier may use. The ones available to you, with the microarchitectures each supports, are returned as CoreClasses by GET /users/{UserID}.

MemorySize
integer >= 0
Deprecated

Accepted and ignored. The Signaloid Cloud Platform assigns the memory size from the Core class, and responses report that value.

DependencyTracking
string
Enum: "None" "Basic" "Advanced"

Required for every class except r7i, unless the Microarchitecture is Bypass. Both always have None. See #/DependencyTracking.

Responses

Request samples

Content type
application/json
Example
{
  • "Microarchitecture": "Athens",
  • "Precision": 10000000,
  • "Name": "string",
  • "Class": "C0Pro",
  • "MemorySize": 0,
  • "DependencyTracking": "None"
}

Response samples

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

Drives

List Drives

Returns the Drives of the account. This list is paginated.

Authorizations:
ApiKeybearerAuth
query Parameters
cursor
string

Where to resume the listing. Omit it on the first request. On later requests, pass Pagination.Links.Next.Cursor from the previous response, unchanged. See Pagination.

startKey
string (driveID) drv_[a-z0-9]{32}
Deprecated

Deprecated. Use cursor instead. Where to resume the list of Drives. Use for paginating responses. Pass back the ContinuationKey returned by the previous response. A value that is not a well-formed ID is refused with 400 Bad Request.

limit
integer
Default: 25

The maximum number of items to return in one page. The default is 25 and the maximum 100. See Pagination.

Responses

Response samples

Content type
application/json
{}

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

Mount location. The application opens the files of the data source under this path. Use a relative path, such as sd0/, which the application opens as sd0/.... The empty string mounts the data source at the root of the application's directory.

For security reasons, the path must stay inside the application's directory. An absolute path, or one that leaves the directory through .., returns 400 Bad Request. Creating a Task checks the data sources it inherits from its Build as well as the ones in the request.

ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "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

Mount location. The application opens the files of the data source under this path. Use a relative path, such as sd0/, which the application opens as sd0/.... The empty string mounts the data source at the root of the application's directory.

For security reasons, the path must stay inside the application's directory. An absolute path, or one that leaves the directory through .., returns 400 Bad Request. Creating a Task checks the data sources it inherits from its Build as well as the ones in the request.

ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "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

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. This list is paginated.

Before pagination, this list returned every item in one response. See Pagination.

Authorizations:
ApiKeybearerAuth
query Parameters
cursor
string

Where to resume the listing. Omit it on the first request. On later requests, pass Pagination.Links.Next.Cursor from the previous response, unchanged. See Pagination.

limit
integer
Default: 100

The maximum number of items to return in one page. The default and the maximum are 100. See Pagination.

Responses

Response samples

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

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

When the key should expire, as a Unix timestamp in seconds. Defaults to null, which creates a key that never expires.

The unit is seconds, not the milliseconds used by the Build and Task endpoints. A millisecond value here is read as a date far in the future. A value in the past is rejected with 400 Bad Request.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "Object": "Key",
  • "Key": "scce_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2_12345678",
  • "KeyID": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  • "Name": "My New API Key",
  • "Owner": "usr_000000000000000000000000000000ab",
  • "ValidUntil": 1830297599,
  • "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",
  • "Tier": "string",
  • "Allowance": {
    },
  • "CoreClasses": [
    ],
  • "Microarchitectures": [
    ],
  • "FieldConstraints": {
    }
}

List Organization Invitations

Returns the pending organization invitations for the currently authenticated user. This list is paginated.

Before pagination, this list returned every item in one response. See Pagination.

Authorizations:
ApiKeybearerAuth
query Parameters
cursor
string

Where to resume the listing. Omit it on the first request. On later requests, pass Pagination.Links.Next.Cursor from the previous response, unchanged. See Pagination.

limit
integer
Default: 100

The maximum number of items to return in one page. The default and the maximum are 100. See Pagination.

Responses

Response samples

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

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",
  • "Tier": "string",
  • "Allowance": {
    },
  • "CoreClasses": [
    ],
  • "Microarchitectures": [
    ],
  • "FieldConstraints": {
    }
}

List Organization Users

Returns the active members of the specified organization with status=Active, or its pending invitations with status=Pending. Each list is paginated on its own.

Without status, the response is the one from before pagination, with both lists whole, as Users and Pending, with ActiveCount, PendingCount and TotalCount, and no Pagination. It is deprecated. Such a request cannot send cursor or limit, and is refused with 400 Bad Request when the two lists together do not fit in one response.

Authorizations:
ApiKeybearerAuth
path Parameters
OrganizationID
required
string

The identifier of the Organization resource.

query Parameters
status
string
Enum: "Active" "Pending"

Which list to return, Active members or Pending invitations. A cursor works only with the status it came from. Without it, the response is the deprecated one with both lists.

cursor
string

Where to resume the listing. Omit it on the first request. On later requests, pass Pagination.Links.Next.Cursor from the previous response, unchanged. See Pagination.

limit
integer
Default: 100

The maximum number of items to return in one page. The default and the maximum are 100. See Pagination.

Responses

Response samples

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

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, or cancels a pending invitation.

A member invitation that has been sent but is not yet accepted has no UserID. You can cancel the pending invitation by passing the invited email address in the same path position.

Authorizations:
ApiKeybearerAuth
path Parameters
OrganizationID
required
string

The identifier of the Organization resource.

required
UserID (string) or string

The identifier of the User to remove. This is their UserID for a member of the organization, or the email address the invitation was sent to for a pending invitation.

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
required
string or Array of numbers

A Ux string, or a list of numeric samples.

One of
string

A Ux string, or a list of numeric samples.

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.

This list is paginated.

Authorizations:
ApiKeybearerAuth
query Parameters
cursor
string

Where to resume the listing. Omit it on the first request. On later requests, pass Pagination.Links.Next.Cursor from the previous response, unchanged. See Pagination.

startKey
string (RepositoryID) rep_[a-z0-9]{32}
Deprecated

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

limit
integer
Default: 25

The maximum number of items to return in one page. The default is 25 and the maximum 100. See Pagination.

Responses

Response samples

Content type
application/json
{
  • "UserID": "string",
  • "Repositories": [
    ],
  • "Count": 0,
  • "Pagination": {
    },
  • "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> non-empty

The URL of the git repository. Unlike the other required string fields on this schema, this one may not be the empty string.

Commit
required
string >= 0 characters

The commit to check out. Required to be present, but need not be a pinned commit hash.

Pass HEAD to track the tip of Branch instead of pinning a commit. A Repository stored with HEAD picks up new commits on each subsequent Build, without the Repository needing to be updated. Pass an explicit commit hash to pin the Repository to exactly that commit.

Branch
required
string >= 0 characters

The branch to check out. Required to be present, but may be the empty string, which selects the repository's default branch as reported by the git host.

Note that the empty string and the default branch's actual name are not interchangeable for duplicate detection. Connecting the same repository once with "" and once with, say, main creates two distinct Repository resources and does not raise 409 Conflict, even when both resolve to the same branch. GET /repositories/lookup also requires a non-empty branch, so a Repository stored with "" cannot be found through that endpoint. Retrieve it with GET /repositories instead.

BuildDirectory
required
string >= 0 characters

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.

Required to be present, but may be the empty string, which builds from 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 lowest-precision C0Pro default Core available to your account.

A value naming one of the retired C0 default Cores returns 400 Bad Request with a message naming the equivalent C0Pro default Core to use instead.

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

Mount location. The application opens the files of the data source under this path. Use a relative path, such as sd0/, which the application opens as sd0/.... The empty string mounts the data source at the root of the application's directory.

For security reasons, the path must stay inside the application's directory. An absolute path, or one that leaves the directory through .., returns 400 Bad Request. Creating a Task checks the data sources it inherits from its Build as well as the ones in the request.

ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "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. A Build for an r7i Core ignores this 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": "HEAD",
  • "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.

query Parameters
remove
Array of strings
Default: ""
Items Enum: "DataSources" "Core" "TraceVariables"

Repository fields to reset, rather than assign. Only DataSources, Core, and TraceVariables can be removed. Any other field is ignored. Repeat the parameter to reset more than one field, for example ?remove=Core&remove=DataSources.

Removing a field restores the platform default for it. With no Core, a Build uses the default Core with the lowest precision available to your account. With no DataSources or TraceVariables, a Build inherits an empty list.

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

Request Body schema: application/json

Required unless the remove query parameter is supplied, in which case any body is ignored.

non-empty
RemoteURL
string <uri>

The URL of the git repository. Changing this or Branch moves the Repository's duplicate-detection slot, so a change that collides with another of your Repositories is rejected with 409 Conflict.

Commit
string >= 0 characters

The commit to check out. May be a pinned commit hash, or HEAD to track the tip of Branch so that subsequent Builds pick up new commits without further updates to the Repository.

Branch
string >= 0 characters

The branch to check out. May be the empty string, which selects the repository's default branch as reported by the git host. Changing this moves the Repository's duplicate-detection slot. See RemoteURL.

BuildDirectory
string >= 0 characters

The directory in the repository that the Signaloid Cloud Engine should use as working directory when building the repository application, relative to the root of the repository. May be the empty string, which builds from the root of the repository.

Arguments
string >= 0 characters

Default command-line arguments that the Signaloid Cloud Engine should pass when executing the built repository application. May be the empty string, meaning no arguments.

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

The ID of the Core to use for building. Use ?remove=Core to clear it, after which Builds fall back to the lowest-precision C0Pro default Core available to your account.

A value naming one of the retired C0 default Cores returns 400 Bad Request with a message naming the equivalent C0Pro default Core to use instead. This is the endpoint to use to move a Repository off a retired Core.

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

Default data sources to use with this repository. Use ?remove=DataSources to clear the list.

Array ([ 0 .. 5 ] items)
Object
required
string
Value: "DataSource"
Location
required
string

Mount location. The application opens the files of the data source under this path. Use a relative path, such as sd0/, which the application opens as sd0/.... The empty string mounts the data source at the root of the application's directory.

For security reasons, the path must stay inside the application's directory. An absolute path, or one that leaves the directory through .., returns 400 Bad Request. Creating a Task checks the data sources it inherits from its Build as well as the ones in the request.

ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "Bucket" "Drive" "SignaloidCloudStorage"
Array of objects (TraceVariableRequest)

The default variables that the Signaloid Cloud Compute Engine should trace when executing the Repository application. Use ?remove=TraceVariables to clear the list. A Build for an r7i Core ignores this 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": "HEAD",
  • "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.

This list is paginated.

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

The identifier of the connected Repository resource.

query Parameters
cursor
string

Where to resume the listing. Omit it on the first request. On later requests, pass Pagination.Links.Next.Cursor from the previous response, unchanged. See Pagination.

startKey
string^#BUILD#CREATED#[0-9]{4}-[0-9]{2}-[0-9]{2}T[0...
Deprecated

Deprecated. Use cursor instead. 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.

limit
integer
Default: 25

The maximum number of items to return in one page. The default is 25 and the maximum 100. See Pagination.

Responses

Response samples

Content type
application/json
{
  • "RepositoryID": "string",
  • "Builds": [
    ],
  • "Count": 0,
  • "Pagination": {
    },
  • "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". A build for an r7i Core cannot discover variables, so "true" returns 400 Bad Request.

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

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

Using a default CoreID of the retired C0 Core class returns 400 Bad Request. The response message suggests the equivalent C0Pro default Core to use instead.

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.

A build for an r7i Core cannot trace variables. A non-empty list in the request returns 400 Bad Request, and the build ignores the Repository's TraceVariables.

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, C0-microSD-plus, and C0-SD Core classes, which otherwise return 403 Forbidden.

Array ([ 0 .. 5 ] items)
Object
required
string
Value: "DataSource"
Location
required
string

Mount location. The application opens the files of the data source under this path. Use a relative path, such as sd0/, which the application opens as sd0/.... The empty string mounts the data source at the root of the application's directory.

For security reasons, the path must stay inside the application's directory. An absolute path, or one that leaves the directory through .., returns 400 Bad Request. Creating a Task checks the data sources it inherits from its Build as well as the ones in the request.

ResourceID
required
string
ResourceType
required
string (resourceType)
Enum: "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 sets a build as public. Any other value, or 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. A token that cannot be parsed 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, or with any other field, is rejected with 400 Bad Request.

Payload
required
string

A Ux 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.

This list is paginated.

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.

cursor
string

Where to resume the listing. Omit it on the first request. On later requests, pass Pagination.Links.Next.Cursor from the previous response, unchanged. See Pagination.

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

Deprecated. Use cursor instead. 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. Unexpanded listings never get the busy-database 503.

limit
integer [ 1 .. 500 ]
Default: 25

The maximum number of Tasks to return in one page. The default and the maximum are 25 for expanded responses and 500 when noexpand=true. See Pagination.

Responses

Response samples

Content type
application/json
{
  • "UserID": "string",
  • "Count": 0,
  • "Pagination": {
    },
  • "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. A Task whose Build is not public returns 404 Not Found.

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. An optional query parameter skips the cache. If a Task did not write to a stream, then its corresponding body is empty. A failure to read the output returns 404 Not Found, and can be temporary.

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"

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
{
  • "Allowance": {
    },
  • "CoreClasses": [
    ],
  • "CreatedAt": 1642170191405,
  • "FieldConstraints": {
    },
  • "Industry": "robotics",
  • "Microarchitectures": [
    ],
  • "Object": "User",
  • "OnboardingState": {
    },
  • "Preferences": {
    },
  • "ResourceUsage": {
    },
  • "Role": "engineering",
  • "Tier": "FreeTier",
  • "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
{
  • "Allowance": {
    },
  • "CoreClasses": [
    ],
  • "CreatedAt": 1642170191405,
  • "FieldConstraints": {
    },
  • "Industry": "robotics",
  • "Microarchitectures": [
    ],
  • "Object": "User",
  • "OnboardingState": {
    },
  • "Preferences": {
    },
  • "ResourceUsage": {
    },
  • "Role": "engineering",
  • "Tier": "FreeTier",
  • "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.

This parameter can be combined with a request body, or used on its own with an empty body. A key that appears both in the body and in this parameter is removed. A request that supplies neither a body nor this parameter is rejected with 400 Bad Request.

Request Body schema: application/json
Preferences
object
object

Map of onboarding progress flags. All values must be booleans, at most 50 keys per request.

property name*
additional property
boolean
Role
string or null <= 64 characters

The user's role. Free-form string of printable characters. Send null to clear the stored value.

Industry
string or null <= 64 characters

The user's industry. Free-form string of printable characters. Send null to clear the stored value.

Responses

Request samples

Content type
application/json
Example
{
  • "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.

The entries are newest first, and the list is paginated. Each page continues with the entries older than the last one of the page before.

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 first request. A later page sent with cursor and without startTime keeps the window of the first page, and the Pagination links carry it.

endTime
integer <int64>

End of the query window, as a Unix timestamp in milliseconds. Defaults to the time of the first request. A later page sent with cursor and without endTime keeps the window of the first page, and the Pagination links carry it.

cursor
string

Where to resume the listing. Omit it on the first request. On later requests, pass Pagination.Links.Next.Cursor from the previous response, unchanged. See Pagination.

limit
integer
Default: 100

The maximum number of log entries to return in one page. The default is 100 and the maximum 10000. See Pagination.

Responses

Response samples

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

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

List Tiers

Returns every subscription tier and its associated limits. It describes what each tier offers, and not the tiers applied to a specific user account. For finding out the limits applied to a user account, use GET /users/{UserID}.

A limit that does not apply on a tier is reported as null.

Authorizations:
ApiKeybearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Webhooks

Task Status Changed Webhook

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

Event types

  • Initialising
  • In Progress
  • Rescheduled
  • Completed
  • Cancelled
  • Stopped

No event is sent for Accepted. A Task canceled while Accepted sends no events at all, so also read its status.

Completed, Cancelled and Stopped are terminal. There is no Failed status. A task that failed has status Stopped with the reason in Message.

Verifying a delivery

Each delivery is signed. See "Verifying webhook deliveries" on POST /webhooks.

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

Webhook payload version.

ID
required
string^whevt_[a-f0-9]{32}$

Unique ID of this delivery. The same value is sent in the Signaloid-Webhook-Id header.

Event
required
string

The event that triggered the delivery.

Created
required
string <date-time>

Time when the event occurred.

required
object
TaskID
required
string^tsk_[a-zA-Z0-9]{32}$
Status
required
string
Enum: "Accepted" "Initialising" "Rescheduled" "In Progress" "Completed" "Cancelled" "Stopped"
  • Accepted: The Task is accepted and queued for execution. The Task is inactive.
  • Initialising: The Signaloid Cloud Compute Engine has picked up the Task and is initializing the infrastructure to execute it. The Task is active.
  • Rescheduled: The Signaloid Cloud Compute Engine is rescheduling the Task to another worker, due to an interruption on the previous worker. The Task is active.
  • In Progress: The Task is running. The Task is active.
  • Completed: The Task exited with a zero exit code. The Task is inactive.
  • Cancelled: The Task was canceled before it finished. The Task is inactive.
  • Stopped: The Task exited with a non-zero exit code. The Task is inactive.

No status event is sent for Accepted. The first event is usually Initialising, or Rescheduled if the Task is rescheduled before it starts. A Task canceled while Accepted sends no events at all.

Message
string

Optional status message

UpdatedAt
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "Version": "2.0",
  • "ID": "whevt_1234567890abcdef1234567890abcdef",
  • "Event": "task-status",
  • "Created": "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

  • Initialising
  • In Progress
  • Rescheduled
  • Completed
  • Cancelled
  • Stopped

No event is sent for Accepted. A Build canceled while Accepted sends no events at all, so also read its status.

Completed, Cancelled and Stopped are terminal. There is no Failed status. A build that failed has status Stopped with the reason in Message.

Verifying a delivery

Each delivery is signed. See "Verifying webhook deliveries" on POST /webhooks.

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

Webhook payload version.

ID
required
string^whevt_[a-f0-9]{32}$

Unique ID of this delivery. The same value is sent in the Signaloid-Webhook-Id header.

Event
required
string

The event that triggered the delivery.

Created
required
string <date-time>

Time when the event occurred.

required
object
BuildID
required
string^bld_[a-zA-Z0-9]{32}$
Status
required
string
Enum: "Accepted" "Initialising" "Rescheduled" "In Progress" "Completed" "Cancelled" "Stopped"
  • Accepted: The Build is accepted and queued for execution. The Build is inactive.
  • Initialising: The Signaloid Cloud Compute Engine has picked up the Build and is initializing the infrastructure to execute it. The Build is active.
  • Rescheduled: The Signaloid Cloud Compute Engine is rescheduling the Build to another worker, due to an interruption on the previous worker. The Build is active.
  • In Progress: The Build is running. The Build is active.
  • Completed: The Build exited with a zero exit code. The Build is inactive.
  • Cancelled: The Build was canceled before it finished. The Build is inactive.
  • Stopped: The Build exited with a non-zero exit code. The Build is inactive.

No status event is sent for Accepted. The first event is usually Initialising, or Rescheduled if the Build is rescheduled before it starts.

Message
string

Optional status message

UpdatedAt
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "Version": "2.0",
  • "ID": "whevt_1234567890abcdef1234567890abcdef",
  • "Event": "build-status",
  • "Created": "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.

Verifying a delivery

Each delivery is signed. See "Verifying webhook deliveries" on POST /webhooks.

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

Webhook payload version.

ID
required
string^whevt_[a-f0-9]{32}$

Unique ID of this delivery. The same value is sent in the Signaloid-Webhook-Id header.

Event
required
string

The event that triggered the delivery.

Created
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 or canceled

Responses

Request samples

Content type
application/json
{
  • "Version": "2.0",
  • "ID": "whevt_1234567890abcdef1234567890abcdef",
  • "Event": "task-count",
  • "Created": "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.

Verifying a delivery

Each delivery is signed. See "Verifying webhook deliveries" on POST /webhooks.

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

Webhook payload version.

ID
required
string^whevt_[a-f0-9]{32}$

Unique ID of this delivery. The same value is sent in the Signaloid-Webhook-Id header.

Event
required
string

The event that triggered the delivery.

Created
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 or canceled

Responses

Request samples

Content type
application/json
{
  • "Version": "2.0",
  • "ID": "whevt_1234567890abcdef1234567890abcdef",
  • "Event": "build-count",
  • "Created": "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.

Verifying a delivery

Each delivery is signed. See "Verifying webhook deliveries" on POST /webhooks.

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

Webhook payload version.

ID
required
string^whevt_[a-f0-9]{32}$

Unique ID of this delivery. The same value is sent in the Signaloid-Webhook-Id header.

Event
required
string

The event that triggered the delivery.

Created
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": "2.0",
  • "ID": "whevt_1234567890abcdef1234567890abcdef",
  • "Event": "task-stats",
  • "Created": "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.

Verifying a delivery

Each delivery is signed. See "Verifying webhook deliveries" on POST /webhooks.

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

Webhook payload version.

ID
required
string^whevt_[a-f0-9]{32}$

Unique ID of this delivery. The same value is sent in the Signaloid-Webhook-Id header.

Event
required
string

The event that triggered the delivery.

Created
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": "2.0",
  • "ID": "whevt_1234567890abcdef1234567890abcdef",
  • "Event": "build-stats",
  • "Created": "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:

  • Initialising - Task is being set up
  • In Progress - Task is actively running
  • Rescheduled - Task has been rescheduled, and will return to Initialising
  • Completed - Task finished successfully
  • Cancelled - Task was canceled by user
  • Stopped - Task was stopped by system

No event is sent for Accepted. A Task canceled while Accepted sends no events at all, so also read its status.

Completed, Cancelled and Stopped are terminal and no further status event is sent for that task. There is no separate failure status. A task that fails is reported as Stopped, with the reason in Message. Clients that need to tell failure apart from a deliberate stop should read the Message rather than waiting for a status value that will never arrive.

Data includes: TaskID, Status, Message, and UpdatedAt.

2. Build status changed (build-status)

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

  • Initialising - Build is being set up
  • In Progress - Build is actively running
  • Rescheduled - Build has been rescheduled, and will return to Initialising
  • Completed - Build finished successfully
  • Cancelled - Build was canceled by user
  • Stopped - Build was stopped by system

No event is sent for Accepted. A Build canceled while Accepted sends no events at all, so also read its status.

Completed, Cancelled and Stopped are terminal. No further status event is sent for that build. There is no separate failure status. A build that fails is reported as Stopped, with the reason in Message.

Data includes: BuildID, Status, Message, and UpdatedAt.

3. Task count changed (task-count)

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

Data includes: UserID, Object, and ResourceUsage with IncrementTaskCount and DecrementTaskCount.

4. Build count changed (build-count)

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

Data includes: UserID, Object, and ResourceUsage with IncrementBuildCount and DecrementBuildCount.

5. Task stats changed (task-stats)

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

Data includes: UserID, Object, and ResourceUsage with TotalDynamicInstructions and TotalExecutionTime.

6. Build stats changed (build-stats)

Triggered when a user's build stats are updated.

Data includes: UserID, Object, and ResourceUsage with TotalBuildSize and TotalBuildTime.

Webhook payload structure

Every delivery is a POST with this body:

{
  "Version": "2.0",
  "ID": "whevt_[32-char-hex]",
  "Event": "task-status|build-status|task-count|build-count|task-stats|build-stats",
  "Created": "2024-03-20T10:00:00Z",
  "Data": {
    // Event-specific data varies by event type
  }
}

Version 2.0 made every field PascalCase, including those inside Data. Version 1.0 used version, id, event, created and data, with taskId, buildId, status, message and updatedAt inside data. It is no longer sent.

Verifying webhook deliveries

Each delivery carries these headers:

  • Signaloid-Webhook-Id: the delivery's ID.
  • Signaloid-Webhook-Timestamp: the Unix time, in seconds, when it was signed.
  • Signaloid-Webhook-Signature: sha256= followed by the hex HMAC-SHA256 of <timestamp>.<raw request body>, keyed with the Secret of the webhook.
  • Signaloid-Webhook-Version: the payload Version.

The Secret is returned only in the response that creates the webhook.

Request fields are PascalCase. A request that sends the former lowercase fields, such as url or events, is refused with 400 Bad Request.

A webhook is set to disabled after a run of consecutive failed deliveries.

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

The https URL where webhook events will be sent. It must not point to a private or internal address.

Events
required
Array of strings non-empty
Items Enum: "task-status" "build-status" "task-stats" "build-stats" "task-count" "build-count"

List of events to subscribe to, at least one

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": "failed-500",
  • "LastDeliveryTime": null,
  • "Object": "webhook"
}

List all webhooks

Retrieves the webhooks of the authenticated user. This list is paginated.

Before pagination, this list returned every item in one response. See Pagination.

Authorizations:
ApiKeybearerAuth
query Parameters
cursor
string

Where to resume the listing. Omit it on the first request. On later requests, pass Pagination.Links.Next.Cursor from the previous response, unchanged. See Pagination.

limit
integer
Default: 100

The maximum number of items to return in one page. The default and the maximum are 100. See Pagination.

Responses

Response samples

Content type
application/json
{
  • "Webhooks": [
    ],
  • "Count": 4,
  • "Pagination": {
    }
}

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": "failed-500",
  • "LastDeliveryTime": null,
  • "Object": "webhook"
}

Update a webhook

Updates the configuration of an existing webhook. Request fields are PascalCase. A request that sends the former lowercase fields, such as url or status, is refused with 400 Bad Request.

Authorizations:
ApiKeybearerAuth
path Parameters
WebhookID
required
string

The webhook ID

Request Body schema: application/json
required
non-empty
URL
string <uri>
Events
Array of strings non-empty
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": "failed-500",
  • "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:

  • Initialising - Build environment is being set up
  • In Progress - Build is actively running
  • Rescheduled - Build has been rescheduled
  • Completed - Build finished successfully
  • Cancelled - Build was canceled by user
  • Stopped - Build was stopped by system

No event is sent for Accepted. A Build canceled while Accepted sends no events at all, so also read its status.

Data includes: BuildID, Status, Message, and UpdatedAt.

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

Notifies about task lifecycle state changes:

  • Initialising - Task environment is being set up
  • In Progress - Task is actively running
  • Rescheduled - Task has been rescheduled
  • Completed - Task finished successfully
  • Cancelled - Task was canceled by user
  • Stopped - Task was stopped by system

No event is sent for Accepted. A Task canceled while Accepted sends no events at all, so also read its status.

Data includes: TaskID, Status, Message, and UpdatedAt.

A public task (one run with IsPublic set) sends its status events only to public-task-status/{taskId} on the public realtime endpoint, not to its owner's task-status/{userId} channel.

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

Provides build stats updates:

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

Data includes: UserID, Object, and ResourceUsage with 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

Data includes: UserID, Object, and ResourceUsage with TotalDynamicInstructions and TotalExecutionTime.

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

Updates about build count changes:

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

Data includes: UserID, Object, and ResourceUsage with IncrementBuildCount and DecrementBuildCount.

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

Updates about task count changes:

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

Data includes: UserID, Object, and ResourceUsage with IncrementTaskCount and DecrementTaskCount.

Channel names

{userId} in a channel name is your user ID without its usr_ prefix. For the user usr_1234567890abcdef1234567890abcdef, subscribe to build-status/1234567890abcdef1234567890abcdef. The idToChannel helper in the example below strips the prefix.

Connection protocol

  1. Connect with authorization header
  2. Send a 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.

Event structure

Each data message carries one event in its event field, as a JSON string. Parsed, every event has this shape:

{
  "EventType": "task-status",
  "Timestamp": "2024-03-20T10:00:00Z",
  "Data": {
    "TaskID": "tsk_1234567890abcdef1234567890abcdef",
    "Status": "In Progress",
    "Message": "Task started successfully",
    "UpdatedAt": "2024-03-20T10:00:00Z"
  }
}

EventType names the channel kind, such as task-status or build-stats. Data varies by channel, as listed above. These fields are PascalCase. The envelope fields (type, id, channel, event) belong to the AWS AppSync Events protocol and stay lowercase.

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": "task-status/1234567890abcdef1234567890abcdef",
  "event": "<the event, as a JSON string, on data messages>"
}

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) { const parts = id.split("_"); return parts.length > 1 ? parts[1] : id; }

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:", JSON.parse(msg.event));
    });
    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 public endpoint carries one channel, for the status of public tasks. The public-build-status, public-task-stats, public-build-stats, public-task-count and public-build-count channels accept subscriptions, but no events are published on them.

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

Notifies about task lifecycle state changes:

  • Initialising - Task environment is being set up
  • In Progress - Task is actively running
  • Rescheduled - Task has been rescheduled
  • Completed - Task finished successfully
  • Cancelled - Task was canceled by user
  • Stopped - Task was stopped by system

No event is sent for Accepted. A Task canceled while Accepted sends no events at all, so also read its status.

Data includes: TaskID, Status, Message, and UpdatedAt.

Channel names

{taskId} in a channel name is the task ID without its tsk_ prefix. For the task tsk_1234567890abcdef1234567890abcdef, subscribe to public-task-status/1234567890abcdef1234567890abcdef. The idToChannel helper in the example below strips the prefix.

Connection protocol

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

Event structure

Events have the same EventType, Timestamp and Data shape as on the private real-time endpoint.

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": "public-task-status/1234567890abcdef1234567890abcdef",
  "event": "<the event, as a JSON string, on data messages>"
}

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) { const parts = id.split("_"); return parts.length > 1 ? parts[1] : id; }

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(`public-task-status/${taskId}`);
        resolve();
      }
      if (msg.type === "data") console.log("Event:", JSON.parse(msg.event));
    });
    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"
}