Skip to main content
Glows.ai
API docs by Redocly

GLOWS SDK HTTP API (v1)

GLOWS SDK v1 exposes instance lifecycle, image submission, resource spec, network, and snapshot APIs under /sdk/v1.

Authentication uses an SDK token in the Authorization: Bearer <token> header. The server also accepts an Authorization query parameter and copies it into the header before JWT validation.

Application errors are returned as JSON bodies with code and msg. Most application errors use HTTP status 200; rate limiting can return HTTP 429 with a plain text body.

This contract describes the public SDK HTTP API surface.

Instance

Create, query, list, count, and cancel SDK-created compute instances.

Query one instance

Query an instance by request_id or meta_key.

request_id is the instanceID returned by create/list/query responses. The server accepts both resource IDs such as ins-... and the legacy hash ID fallback. meta_key is the globally unique custom key supplied as custom_meta_key during creation.

Authorizations:
bearerAuth
query Parameters
request_id
string <= 64 characters
Example: request_id=ins-boyqp4g8

Instance resource ID returned as instance.instanceID, or a legacy hash ID fallback.

meta_key
string <= 64 characters
Example: meta_key=order.123456

User-supplied globally unique custom_meta_key.

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 198 199 206 208 215

SDK-relevant application error code. 0 means success.

msg
string
object (VisibleInstance)

Response samples

Content type
application/json
Example
{
  • "code": 0,
  • "msg": "",
  • "instance": {
    }
}

Create an Instance via SDK

Create a container or VM instance from an image or snapshot.

Authorizations:
bearerAuth
Request Body schema: application/json
required
One of
from_image_id
required
string <= 64 characters

Base image resource ID.

gpu_name
required
string <= 128 characters

GPU model name.

custom_meta_key
required
string <= 64 characters

Globally unique custom key used for idempotent business lookup.

instance_category
required
string (InstanceCategory)
Default: "container"
Enum: "container" "vm"
region_name
required
string <= 128 characters

Required region display/name value that maps to a platform domain.

remark
string <= 32 characters

Human-readable remark.

cmd
string <= 512 characters

Instance entry command.

envs
string <= 512 characters

Environment variable string, for example foo=bar;tik=tok.

ports
string

JSON string of AppPortInput[]. At most one SSH protocol entry is accepted.

unit_qty
integer <int64> >= 0
Default: 1

Number of GPU/CPU resource units to request. 0 or omission defaults to one unit. Applies to both GPU and CPU instance creation. When base_resource.resource_id or base_resource.unit_spec is present and base_resource.unit_qty is greater than zero, base_resource.unit_qty overrides this value.

object (CreateInstanceBaseResource)

Base resource description converted directly into the base resource descriptor. resource_id is the base64-encoded machine class tag, not an SDK res-... resource ID. unit_spec fields are copied into the same base resource. If unit_qty is greater than zero it overrides top-level unit_qty; 0 or omission keeps the top-level value. A base_resource object with only unit_qty is not enough to activate base-resource creation; include resource_id or unit_spec.

object (CreateInstanceExtraResource)

Extra resource description. Extra resources do not have resource IDs or GPU fields.

net_ids
Array of strings <= 1 items [ items <= 64 characters ]

Private network IDs returned by listNetworks. The current server supports one network.

network_type
integer <int32> (NetworkType)
Enum: 0 1 2 3 4 5 6 7

Numeric network type. In SDK network APIs, omitted or 0 means mesh/UserVXLAN for compatibility; 6 means NAT4 public-IP network for list operations.

public_ip_id
string <= 64 characters

Public/NAT network resource ID. When present and valid, server forces network_type to NAT4.

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 198 199 206 208 215

SDK-relevant application error code. 0 means success.

msg
string
object (VisibleInstance)

Request samples

Content type
application/json
Example
{
  • "from_image_id": "img-87p9kq26",
  • "custom_meta_key": "order.123456",
  • "remark": "this is from sdk",
  • "envs": "foo=bar",
  • "gpu_name": "NVIDIA GeForce RTX 4090",
  • "unit_qty": 2,
  • "instance_category": "container",
  • "region_name": "Region-01",
  • "ports": "[{\"port\":7890,\"protocol\":2}]"
}

Response samples

Content type
application/json
Example
{
  • "code": 0,
  • "msg": "",
  • "instance": {
    }
}

Cancel an instance via SDK

Cancel an instance by request_id or meta_key.

The server cancels only instances owned by the authenticated SDK user and created with SDK source semantics. Invalid IDs, non-owned instances, and missing query parameters return ParamIllegal.

Authorizations:
bearerAuth
query Parameters
request_id
string <= 64 characters
Example: request_id=ins-boyqp4g8

Instance resource ID returned as instance.instanceID, or a legacy hash ID fallback.

meta_key
string <= 64 characters
Example: meta_key=order.123456

User-supplied globally unique custom_meta_key.

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 198 199 206 208 215

SDK-relevant application error code. 0 means success.

msg
string

Response samples

Content type
application/json
Example
{
  • "code": 0,
  • "msg": ""
}

Count instances by status

Return a sparse status-to-count map for the authenticated SDK user.

Authorizations:
bearerAuth

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 198 199 206 208 215

SDK-relevant application error code. 0 means success.

msg
string
object

Sparse map from status name to instance count.

Response samples

Content type
application/json
{
  • "code": 0,
  • "msg": "",
  • "stats": {
    }
}

List instances

List instances for the authenticated SDK user.

page and per_page are required by the server binding. per_page must be no greater than 20. Passing an empty statuses list returns all statuses. Unknown status names are currently ignored by the server.

Authorizations:
bearerAuth
query Parameters
page
required
integer <uint32> >= 1
Example: page=1

1-based page number.

per_page
required
integer <uint32> [ 1 .. 20 ]
Example: per_page=10

Page size. The current server rejects values greater than 20.

ascending
boolean
Default: false

Sort by creation time ascending when true; descending when false.

statuses
Array of strings (NodeStatusName)
Items Enum: "InvalidNodeStatus" "Pending" "Running" "Exited" "Finished" "Rebooted" "Canceling" "Unavail" "Pausing" "Paused" "Resuming" "Snapshotted" "ExitSnapshotted" "Migrating" "Checkpointed" "SchedInit" "SchedQueued" "PriceChanged"

Repeatable status filter, for example statuses=Running&statuses=Pending.

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 198 199 206 208 215

SDK-relevant application error code. 0 means success.

msg
string
object (Pagination)
Array of objects (VisibleInstance)

Response samples

Content type
application/json
{
  • "code": 0,
  • "msg": "",
  • "pagination": {
    },
  • "instances": [
    ]
}

Image

Submit one container image registry link and list SDK-visible images.

Submit one container image link

Submit a single container registry image link for the authenticated SDK user.

The SDK surface only accepts image_link. The server creates a private user-owned image with registry URL provider semantics and returns the encoded image resource ID.

Authorizations:
bearerAuth
Request Body schema: application/json
required
image_link
required
string <= 512 characters

Single registry image link. Whitespace is rejected.

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 198 199 206 208 215

SDK-relevant application error code. 0 means success.

msg
string
image_id
string

Encoded image resource ID, for example img-....

name
string

Server-generated image name.

Request samples

Content type
application/json
{
  • "image_link": "registry.example.com/team/runtime:cuda12.2"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "msg": "",
  • "image_id": "img-87p9kq26",
  • "name": "sdk-10001-1726810944000000000-runtime"
}

Delete an SDK-owned image

Delete a private image owned by the authenticated SDK user.

The server accepts an encoded image resource ID such as img-..., verifies ownership, resolves the backing image store, and then calls the image manager delete flow. Public images and images owned by another user are rejected.

Authorizations:
bearerAuth
Request Body schema: application/json
required
image_id
required
string <= 64 characters

Encoded image resource ID, for example img-....

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 198 199 206 208 215

SDK-relevant application error code. 0 means success.

msg
string

Request samples

Content type
application/json
{
  • "image_id": "img-87p9kq26"
}

Response samples

Content type
application/json
Example
{
  • "code": 0,
  • "msg": ""
}

List SDK-visible images

Authorizations:
bearerAuth
query Parameters
page
integer <uint32> >= 0
Default: 1
Example: page=1

1-based page number. Omit or pass 0 to use page 1.

per_page
integer <uint32> [ 0 .. 20 ]
Default: 20
Example: per_page=10

Page size. Omit or pass 0 to use the server default of 20; values greater than 20 are rejected.

owned
boolean
Default: false

When true, only return images owned by the authenticated user.

keywords
string <= 100 characters

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 198 199 206 208 215

SDK-relevant application error code. 0 means success.

msg
string
object (Pagination)
Array of objects (SDKImageInfo)

Response samples

Content type
application/json
{
  • "code": 0,
  • "msg": "",
  • "pagination": {
    },
  • "images": [
    ]
}

Spec

List create-instance resource specs by region.

List resource specs

Authorizations:
bearerAuth
query Parameters
machine_category
required
integer <int32> (MachineCategory)
Enum: 0 1 2 3

Machine resource category filter.

from_image_id
required
string <= 64 characters
Example: from_image_id=img-87p9kq26

Image resource ID used to list image-compatible specs.

page
integer <uint32> >= 0
Default: 1
Example: page=1

1-based page number. Omit or pass 0 to use page 1.

per_page
integer <uint32> [ 0 .. 20 ]
Default: 20
Example: per_page=10

Page size. Omit or pass 0 to use the server default of 20; values greater than 20 are rejected.

region_name
string <= 128 characters
Example: region_name=Region-01

Optional region display/name value. When omitted, specs are listed across regions.

by_region
boolean
Default: false

Group response by region. In this mode pagination applies to regions.

instance_category
integer <int32> (SpecInstanceCategory)
Enum: 0 1

Optional container/VM filter. Omit to avoid filtering by instance category.

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 198 199 206 208 215

SDK-relevant application error code. 0 means success.

msg
string
object (Pagination)
Array of objects (SpecInfo)

Filled when by_region is false or omitted; empty when by_region is true.

Array of objects (RegionSpecs)

Filled when by_region is true; empty when by_region is false or omitted.

Response samples

Content type
application/json
Example
{
  • "code": 0,
  • "msg": "",
  • "pagination": {
    },
  • "specs": [
    ],
  • "regions": [ ]
}

Network

Create mesh networks, list mesh or owned NAT4 public-IP networks, and attach instances to mesh networks.

Create a mesh network

Create a user mesh network. network_type is an integer SDK-facing enum; omit it or pass 0 for mesh creation. NAT4 creation is not exposed through the SDK HTTP API.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string <= 32 characters
region_name
required
string <= 128 characters
network_type
integer <int32> (NetworkType)
Enum: 0 1 2 3 4 5 6 7

Numeric network type. In SDK network APIs, omitted or 0 means mesh/UserVXLAN for compatibility; 6 means NAT4 public-IP network for list operations.

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 198 199 206 208 215

SDK-relevant application error code. 0 means success.

msg
string
network_id
string

Encoded network resource ID, for example net-....

Request samples

Content type
application/json
{
  • "network_type": 0,
  • "name": "train-mesh",
  • "region_name": "Region-01"
}

Response samples

Content type
application/json
Example
{
  • "code": 0,
  • "msg": "",
  • "network_id": "net-od7pv75w"
}

List mesh networks or owned public-IP NAT4 networks

List user-owned networks. Omit network_type or pass 0 to list mesh networks. Pass 6 (NAT4) to list the user's purchased public IP networks.

This endpoint returns owned NAT4/public-IP networks, not the available EIP purchase pool.

Authorizations:
bearerAuth
query Parameters
page
integer <uint32> >= 0
Default: 1
Example: page=1

1-based page number. Omit or pass 0 to use page 1.

per_page
integer <uint32> [ 0 .. 20 ]
Default: 20
Example: per_page=10

Page size. Omit or pass 0 to use the server default of 20; values greater than 20 are rejected.

network_type
integer <int32> (NetworkType)
Enum: 0 1 2 3 4 5 6 7

Omit or pass 0 for mesh/UserVXLAN; pass 6 for NAT4 public IP networks.

domain
integer <int32> (Domain)
Default: 0

Domain numeric value. Omit or pass 0 for the default domain.

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 198 199 206 208 215

SDK-relevant application error code. 0 means success.

msg
string
object (Pagination)
Array of objects (VisibleNetwork)

Response samples

Content type
application/json
Example
{
  • "code": 0,
  • "msg": "",
  • "pagination": {
    },
  • "networks": [
    ]
}

Add existing instances to a mesh network

Attach one or more existing user-owned instances to a user-owned mesh network. Duplicate instance_ids are ignored before quota checking. The current request accepts up to 10 instance IDs.

Authorizations:
bearerAuth
Request Body schema: application/json
required
network_id
required
string <= 64 characters
instance_ids
required
Array of strings [ 1 .. 10 ] items [ items <= 64 characters ]

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 198 199 206 208 215

SDK-relevant application error code. 0 means success.

msg
string
network_id
string
endpoint_ids
Array of strings

Request samples

Content type
application/json
{
  • "network_id": "net-od7pv75w",
  • "instance_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "msg": "",
  • "network_id": "net-od7pv75w",
  • "endpoint_ids": [
    ]
}

List network endpoints

Authorizations:
bearerAuth
query Parameters
network_id
required
string <= 64 characters
Example: network_id=net-od7pv75w
page
integer <uint32> >= 0
Default: 1
Example: page=1

1-based page number. Omit or pass 0 to use page 1.

per_page
integer <uint32> [ 0 .. 20 ]
Default: 20
Example: per_page=10

Page size. Omit or pass 0 to use the server default of 20; values greater than 20 are rejected.

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 198 199 206 208 215

SDK-relevant application error code. 0 means success.

msg
string
object (Pagination)
Array of objects (SDKNetworkEndpoint)

Response samples

Content type
application/json
{
  • "code": 0,
  • "msg": "",
  • "pagination": {
    },
  • "endpoints": [
    ]
}

Snapshot

Create snapshots from SDK-managed instances and list snapshots owned by the SDK user.

Create snapshot from a running instance

Create one or more snapshots of a running SDK-managed instance using server-configured SDK snapshot volumes.

Authorizations:
bearerAuth
Request Body schema: application/json
required
instance_id
required
string <= 64 characters
name
string <= 32 characters

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 198 199 206 208 215

SDK-relevant application error code. 0 means success.

msg
string
snapshot_ids
Array of strings
instance_id
string
status
string

Instance status name after snapshot creation; the current success response uses Pausing.

Request samples

Content type
application/json
{
  • "instance_id": "ins-boyqp4g8",
  • "name": "checkpoint-001"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "msg": "",
  • "snapshot_ids": [
    ],
  • "instance_id": "ins-boyqp4g8",
  • "status": "Pausing"
}

List snapshots

Authorizations:
bearerAuth
query Parameters
page
integer <uint32> >= 0
Default: 1
Example: page=1

1-based page number. Omit or pass 0 to use page 1.

per_page
integer <uint32> [ 0 .. 20 ]
Default: 20
Example: per_page=10

Page size. Omit or pass 0 to use the server default of 20; values greater than 20 are rejected.

status
Array of integers <int32> (SnapshotStatus) [ items <int32 > ]
Items Enum: 0 1 2 3 4 5 6 7

Repeatable numeric snapshot status filter. Omit to use server default snapshot listing semantics.

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 198 199 206 208 215

SDK-relevant application error code. 0 means success.

msg
string
object (Pagination)
Array of objects (SDKSnapshotInfo)

Response samples

Content type
application/json
{
  • "code": 0,
  • "msg": "",
  • "pagination": {
    },
  • "snapshots": [
    ]
}

Error Codes

Error codes used by the public SDK API:

code name meaning
0 Success Request succeeded.
1 InternalError Server internal error.
6 ParamIllegal Invalid parameter, missing required field, invalid resource ID, or ownership mismatch.
7 PermissionDenied Permission denied.
10 MetaKeyExist custom_meta_key already exists.
17 DiskQuotaExceeded Disk quota exceeded.
20 IllegalStatus Instance is not in a legal state for the requested operation.
88 OutOfNetCountLimit Network count quota exceeded.
89 EndpointExist Endpoint already exists.
114 TakingSnapNotAllowed Taking snapshot is not allowed.
133 NetNameRepeat Network name already exists.
164 OutOfNetEndpointCountLimit Private network endpoint quota exceeded.
174 ImageAlreadyExists Image already exists.
192 ImagePendingLimitExceeded Image pending limit exceeded.
198 UserNodeQtyExceedQuota User instance quota exceeded.
199 UserSnapQtyExceedQuota User snapshot quota exceeded.
206 InvalidDomainInfo region_name cannot be mapped to a valid domain.
208 RegionAccessDenied The authenticated user has no access to the requested region.
215 NoResourceAvailable No required resource is available.

LLM

Documentation coming soon.

Skills

Documentation coming soon.