Run API reference

Build-provider-neutral workloads, deployments, and revisions.

Published contracts: @socra/run-api@0.4.0.

Base URL

https://run.socra.cloud

Workloads

A stable runnable service or finite job.

Create workload

POST/v1/workloads

Request body

project_idcustomrequired

namestringrequired

min length: 1 · max length: 63 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

kind"service" | "job"optional

default: "service"

portinteger | nulloptional

default: 3000

variablesobjectoptional

default: {}

secretsobjectoptional

release_commandstring[] | nulloptional

default: null

Response

12 fields

idcustomrequired

project_idcustomrequired

namestringrequired

min length: 1 · max length: 63 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

kind"service" | "job"required

portinteger | nullrequired

variablesobjectrequired

default: {}

secretsobjectrequired

default: {}

release_commandstring[] | nullrequired

active_revision_idstring | nullrequired

urlstring | nullrequired

created_atcustomrequired

updated_atcustomrequired

List workloads

GET/v1/workloads

Query parameters

limitintegeroptional

min: 1 · max: 100

afterstringoptional

project_idcustomrequired

Response

2 fields

dataobject[]required

idcustomrequired

project_idcustomrequired

namestringrequired

min length: 1 · max length: 63 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

kind"service" | "job"required

portinteger | nullrequired

variablesobjectrequired

default: {}

secretsobjectrequired

default: {}

release_commandstring[] | nullrequired

active_revision_idstring | nullrequired

urlstring | nullrequired

created_atcustomrequired

updated_atcustomrequired

has_morebooleanrequired

Get workload

GET/v1/workloads/{id}

Path parameters

idcustomrequired

Query parameters

No query parameters

Response

12 fields

idcustomrequired

project_idcustomrequired

namestringrequired

min length: 1 · max length: 63 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

kind"service" | "job"required

portinteger | nullrequired

variablesobjectrequired

default: {}

secretsobjectrequired

default: {}

release_commandstring[] | nullrequired

active_revision_idstring | nullrequired

urlstring | nullrequired

created_atcustomrequired

updated_atcustomrequired

Update workload

PATCH/v1/workloads/{id}

Path parameters

idcustomrequired

Request body

kind"service" | "job"optional

portinteger | nulloptional

variablesobjectoptional

default: {}

secretsobjectoptional

release_commandstring[] | nulloptional

Response

12 fields

idcustomrequired

project_idcustomrequired

namestringrequired

min length: 1 · max length: 63 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

kind"service" | "job"required

portinteger | nullrequired

variablesobjectrequired

default: {}

secretsobjectrequired

default: {}

release_commandstring[] | nullrequired

active_revision_idstring | nullrequired

urlstring | nullrequired

created_atcustomrequired

updated_atcustomrequired

Delete workload

DELETE/v1/workloads/{id}

Path parameters

idcustomrequired

Query parameters

No query parameters

Response

No response body

Deployments

A request to reconcile an immutable image into a workload.

Create deployment

POST/v1/deployments

Request body

project_idcustomrequired

workloadstringrequired

min length: 1 · max length: 63 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

imagestringrequired

pattern: ^[^\s@]+@sha256:[0-9a-f]{64}$

Response

17 fields

idcustomrequired

project_idcustomrequired

workload_idcustomrequired

imagestringrequired

pattern: ^[^\s@]+@sha256:[0-9a-f]{64}$

variablesobjectrequired

default: {}

secret_referencesobjectrequired

default: {}

secretsobjectrequired

default: {}

release_commandstring[] | nullrequired

urlstring | nullrequired

status"queued" | "running" | "succeeded" | "failed" | "cancelled"required

revision_idstring | nullrequired

errorstring | nullrequired

logsstringrequired

created_atcustomrequired

updated_atcustomrequired

started_atcustom | nullrequired

finished_atcustom | nullrequired

List deployments

GET/v1/deployments

Query parameters

limitintegeroptional

min: 1 · max: 100

afterstringoptional

project_idcustomrequired

workload_idcustomoptional

status"queued" | "running" | "succeeded" | "failed" | "cancelled"optional

Response

2 fields

dataobject[]required

idcustomrequired

project_idcustomrequired

workload_idcustomrequired

imagestringrequired

pattern: ^[^\s@]+@sha256:[0-9a-f]{64}$

variablesobjectrequired

default: {}

secret_referencesobjectrequired

default: {}

secretsobjectrequired

default: {}

release_commandstring[] | nullrequired

urlstring | nullrequired

status"queued" | "running" | "succeeded" | "failed" | "cancelled"required

revision_idstring | nullrequired

errorstring | nullrequired

logsstringrequired

created_atcustomrequired

updated_atcustomrequired

started_atcustom | nullrequired

finished_atcustom | nullrequired

has_morebooleanrequired

Get deployment

GET/v1/deployments/{id}

Path parameters

idcustomrequired

Query parameters

No query parameters

Response

17 fields

idcustomrequired

project_idcustomrequired

workload_idcustomrequired

imagestringrequired

pattern: ^[^\s@]+@sha256:[0-9a-f]{64}$

variablesobjectrequired

default: {}

secret_referencesobjectrequired

default: {}

secretsobjectrequired

default: {}

release_commandstring[] | nullrequired

urlstring | nullrequired

status"queued" | "running" | "succeeded" | "failed" | "cancelled"required

revision_idstring | nullrequired

errorstring | nullrequired

logsstringrequired

created_atcustomrequired

updated_atcustomrequired

started_atcustom | nullrequired

finished_atcustom | nullrequired

Get deployment logs

GET/v1/deployments/{id}/logs

Path parameters

idcustomrequired

Query parameters

No query parameters

Response

2 fields

datastringrequired

status"queued" | "running" | "succeeded" | "failed" | "cancelled"required

Get deployment events

GET/v1/deployments/{id}/events

Path parameters

idcustomrequired

Query parameters

No query parameters

Response

1 field

dataobject[]required

type"queued" | "started" | "succeeded" | "failed" | "cancelled"required

atcustomrequired

messagestringrequired

Get deployment health

GET/v1/deployments/{id}/health

Path parameters

idcustomrequired

Query parameters

No query parameters

Response

4 fields

status"pending" | "deploying" | "healthy" | "unhealthy" | "stopped"required

urlstring | nullrequired

revision_idstring | nullrequired

checked_atcustomrequired

Cancel deployment

POST/v1/deployments/{id}/cancel

Path parameters

idcustomrequired

Request body

No request body

Response

17 fields

idcustomrequired

project_idcustomrequired

workload_idcustomrequired

imagestringrequired

pattern: ^[^\s@]+@sha256:[0-9a-f]{64}$

variablesobjectrequired

default: {}

secret_referencesobjectrequired

default: {}

secretsobjectrequired

default: {}

release_commandstring[] | nullrequired

urlstring | nullrequired

status"queued" | "running" | "succeeded" | "failed" | "cancelled"required

revision_idstring | nullrequired

errorstring | nullrequired

logsstringrequired

created_atcustomrequired

updated_atcustomrequired

started_atcustom | nullrequired

finished_atcustom | nullrequired

Revisions

An immutable successful workload configuration.

List revisions

GET/v1/revisions

Query parameters

limitintegeroptional

min: 1 · max: 100

afterstringoptional

project_idcustomrequired

workload_idcustomoptional

Response

2 fields

dataobject[]required

idcustomrequired

project_idcustomrequired

deployment_idcustomrequired

workload_idcustomrequired

numberintegerrequired

greater than: 0 · max: 9007199254740991

imagestringrequired

pattern: ^[^\s@]+@sha256:[0-9a-f]{64}$

variablesobjectrequired

default: {}

secret_referencesobjectrequired

default: {}

secretsobjectrequired

default: {}

release_commandstring[] | nullrequired

created_atcustomrequired

has_morebooleanrequired

Get revision

GET/v1/revisions/{id}

Path parameters

idcustomrequired

Query parameters

No query parameters

Response

11 fields

idcustomrequired

project_idcustomrequired

deployment_idcustomrequired

workload_idcustomrequired

numberintegerrequired

greater than: 0 · max: 9007199254740991

imagestringrequired

pattern: ^[^\s@]+@sha256:[0-9a-f]{64}$

variablesobjectrequired

default: {}

secret_referencesobjectrequired

default: {}

secretsobjectrequired

default: {}

release_commandstring[] | nullrequired

created_atcustomrequired

Roll back to revision

POST/v1/revisions/{id}/rollback

Path parameters

idcustomrequired

Request body

No request body

Response

17 fields

idcustomrequired

project_idcustomrequired

workload_idcustomrequired

imagestringrequired

pattern: ^[^\s@]+@sha256:[0-9a-f]{64}$

variablesobjectrequired

default: {}

secret_referencesobjectrequired

default: {}

secretsobjectrequired

default: {}

release_commandstring[] | nullrequired

urlstring | nullrequired

status"queued" | "running" | "succeeded" | "failed" | "cancelled"required

revision_idstring | nullrequired

errorstring | nullrequired

logsstringrequired

created_atcustomrequired

updated_atcustomrequired

started_atcustom | nullrequired

finished_atcustom | nullrequired

Routes

A Run ingress rule connecting one claimed Hostname to a service workload.

Create route

POST/v1/routes

Request body

project_idcustomrequired

hostnamestringrequired

min length: 3 · max length: 253 · pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$

workloadstringrequired

min length: 1 · max length: 63 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

Response

8 fields

idcustomrequired

project_idcustomrequired

hostname_idcustomrequired

hostnamestringrequired

min length: 3 · max length: 253 · pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$

workloadstringrequired

min length: 1 · max length: 63 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

status"active" | "disabled"required

created_atcustomrequired

updated_atcustomrequired

List routes

GET/v1/routes

Query parameters

limitintegeroptional

min: 1 · max: 100

afterstringoptional

project_idcustomrequired

hostnamestringoptional

min length: 3 · max length: 253 · pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$

workloadstringoptional

min length: 1 · max length: 63 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

status"active" | "disabled"optional

Response

2 fields

dataobject[]required

idcustomrequired

project_idcustomrequired

hostname_idcustomrequired

hostnamestringrequired

min length: 3 · max length: 253 · pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$

workloadstringrequired

min length: 1 · max length: 63 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

status"active" | "disabled"required

created_atcustomrequired

updated_atcustomrequired

has_morebooleanrequired

Get route

GET/v1/routes/{id}

Path parameters

idcustomrequired

Query parameters

No query parameters

Response

8 fields

idcustomrequired

project_idcustomrequired

hostname_idcustomrequired

hostnamestringrequired

min length: 3 · max length: 253 · pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$

workloadstringrequired

min length: 1 · max length: 63 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

status"active" | "disabled"required

created_atcustomrequired

updated_atcustomrequired

Update route

PATCH/v1/routes/{id}

Path parameters

idcustomrequired

Request body

workloadstringoptional

min length: 1 · max length: 63 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

status"active" | "disabled"optional

Response

8 fields

idcustomrequired

project_idcustomrequired

hostname_idcustomrequired

hostnamestringrequired

min length: 3 · max length: 253 · pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$

workloadstringrequired

min length: 1 · max length: 63 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

status"active" | "disabled"required

created_atcustomrequired

updated_atcustomrequired

Delete route

DELETE/v1/routes/{id}

Path parameters

idcustomrequired

Query parameters

No query parameters

Response

No response body