API docs by Redocly

SmartTouch Deployment API (1.0.0)

Download OpenAPI specification:

URL: https://docs.smarttouch.io License: Proprietary

Deploy, manage, and promote IoT services on the SmartTouch Cloud Platform.

The Deployment API lets you apply Service Spec Definitions (SSDs), check service health, roll back to previous revisions, list revision history, and manage canary traffic splits.

Deployment model

SmartTouch uses a GitOps model. In normal operation, deployments are triggered by commits to Git (picked up by Argo CD). Use this API for:

  • Programmatic deployments from CI pipelines
  • Rollbacks that need to bypass the Git merge cycle
  • Canary weight management during gradual rollouts
  • Status checks in automated health gates

Service Spec Definition (SSD)

A service is defined by a smarttouch.yaml file. Submit its content as application/yaml in POST /services. The platform validates the SSD before creating or updating the service.

Environments

All write endpoints require an env query parameter: dev, staging, or prod. Production deployments also require an administrator or platform-engineer role.

Authentication

All endpoints require a bearer token obtained via stctl auth token.

Base URL

https://api.<your-platform-domain>/v1

Related APIs

Services

Service lifecycle — deploy, status, and remove services

List services

Returns all services deployed in the specified environment.

Authorizations:
bearerAuth
query Parameters
env
required
string
Enum: "dev" "staging" "prod"
Example: env=staging

Target deployment environment

status
string
Enum: "healthy" "degraded" "failed" "deploying"

Filter by service health status

page
integer
Default: 1
per_page
integer <= 200
Default: 50

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": [
    ],
  • "meta": {
    }
}

Deploy a service

Apply a Service Spec Definition (SSD) to deploy or update a service.

The SSD is validated before deployment. If validation fails, the service is not changed and the response includes the list of validation errors.

Use dry_run=true to validate the SSD without applying it — useful in CI pipelines.

Deploying to prod requires the platform-engineer or administrator role.

Authorizations:
bearerAuth
query Parameters
env
required
string
Enum: "dev" "staging" "prod"
Example: env=staging

Target deployment environment

dry_run
boolean
Default: false

Validate the SSD without applying it

Request Body schema: application/yaml
required

The smarttouch.yaml SSD content. Submit as application/yaml.

object (SsdContent)

SmartTouch Service Spec Definition (SSD). See the SSD schema reference for all fields.

Responses

Request samples

Content type
application/yaml
{
  "service": {
    "name": "remote-access-service",
    "image": "harbor.smarttouch.local/library/remote-access-service:1.4.2"
  },
  "deployment": {
    "replicas": 3
  },
  "remote-access": {
    "enabled": true,
    "broker-url": "wss://broker.smarttouch.local:8443",
    "protocols": [
      "diagnostics",
      "shell"
    ]
  },
  "observability": {
    "logs": true,
    "metrics": true,
    "traces": true
  },
  "secrets": {
    "vault": [
      {
        "path": "secret/data/remote-access-service/staging/broker-tls",
        "env": "BROKER_TLS_CERT"
      }
    ]
  },
  "config": {
    "env": {
      "LOG_LEVEL": "info",
      "MAX_SESSIONS_PER_DEVICE": "10",
      "SESSION_TTL_SECONDS": "3600"
    }
  }
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Get service status

Returns the current health, replica state, and deployment details for a service.

Authorizations:
bearerAuth
path Parameters
serviceName
required
string
Example: remote-access-service

Service name as defined in the SSD service.name field

query Parameters
env
required
string
Enum: "dev" "staging" "prod"
Example: env=staging

Target deployment environment

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Remove a service

Permanently removes a service from the platform in the specified environment. All running pods are terminated. This action cannot be undone. Requires the platform-engineer or administrator role.

Authorizations:
bearerAuth
path Parameters
serviceName
required
string
Example: remote-access-service

Service name as defined in the SSD service.name field

query Parameters
env
required
string
Enum: "dev" "staging" "prod"
Example: env=staging

Target deployment environment

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "message": "Bearer token is missing or has expired.",
  • "status": 401
}

Revisions

Revision history and rollback operations

List revisions

Returns the deployment history for a service in reverse chronological order.

Authorizations:
bearerAuth
path Parameters
serviceName
required
string
Example: remote-access-service

Service name as defined in the SSD service.name field

query Parameters
env
required
string
Enum: "dev" "staging" "prod"
Example: env=staging

Target deployment environment

page
integer
Default: 1
per_page
integer <= 100
Default: 20

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": [
    ],
  • "meta": {
    }
}

Roll back a service

Roll back a service to a previous revision. If revision is omitted, rolls back to the immediately preceding revision.

Rollback creates a new deployment using the specified revision's image tag. The previous revision becomes available for rollback in turn.

Requires the developer role for dev, platform-engineer for staging and prod.

Authorizations:
bearerAuth
path Parameters
serviceName
required
string
Example: remote-access-service

Service name as defined in the SSD service.name field

query Parameters
env
required
string
Enum: "dev" "staging" "prod"
Example: env=staging

Target deployment environment

Request Body schema: application/json
optional
revision
string

Target revision tag. Omit to roll back to the immediately previous revision.

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Canary

Canary traffic split management

Get canary status

Returns the current canary traffic split and revision details for a service.

Authorizations:
bearerAuth
path Parameters
serviceName
required
string
Example: remote-access-service

Service name as defined in the SSD service.name field

query Parameters
env
required
string
Enum: "dev" "staging" "prod"
Example: env=staging

Target deployment environment

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Set canary weight

Adjust the percentage of traffic routed to the canary version.

Set weight to 100 to promote the canary to stable (all traffic). Set weight to 0 to halt the canary (all traffic returns to stable).

Use POST /services/{serviceName}/canary/promote and POST /services/{serviceName}/canary/halt for explicit promote/halt operations with clearer intent.

Authorizations:
bearerAuth
path Parameters
serviceName
required
string
Example: remote-access-service

Service name as defined in the SSD service.name field

query Parameters
env
required
string
Enum: "dev" "staging" "prod"
Example: env=staging

Target deployment environment

Request Body schema: application/json
required
weight
required
integer [ 0 .. 100 ]

Percentage of traffic to route to the canary version (0–100)

Responses

Request samples

Content type
application/json
{
  • "weight": 50
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Halt canary

Stops the canary deployment and routes all traffic back to the stable revision. The canary revision remains deployed but receives 0% of traffic. Equivalent to setting weight to 0.

Authorizations:
bearerAuth
path Parameters
serviceName
required
string
Example: remote-access-service

Service name as defined in the SSD service.name field

query Parameters
env
required
string
Enum: "dev" "staging" "prod"
Example: env=staging

Target deployment environment

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Promote canary to stable

Promotes the canary version to stable — routes 100% of traffic to it. The previous stable revision is archived in revision history and can be used for rollback.

Authorizations:
bearerAuth
path Parameters
serviceName
required
string
Example: remote-access-service

Service name as defined in the SSD service.name field

query Parameters
env
required
string
Enum: "dev" "staging" "prod"
Example: env=staging

Target deployment environment

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}