API docs by Redocly

Solti API (0.1.0)

Base URL

Base URL for all endpoints is: https://<project-id>.api.solti.run/1

where <project-id> is the project ID of your Solti project.

Authentication

To authenticate, you must provide a valid API key in the X-Solti-Api-Key header. For example:

curl -H "X-Solti-Api-Key: <your-api-key>" https://<project-id>.api.solti.run/1/jobs

The API key can be obtained from either by creating an API key by this API or by Solti's web console.

Account & Organizations & Projects

Endpoints for account, organization, and project management.

These are global (non-project-scoped) endpoints and accept OAuth user authentication only (Solti CLI / SDKs). API Key authentication is rejected because API keys are project-scoped machine-user credentials.

Organization roles: owner, admin, member (see the Zitadel spec §4).

Get the current account

Returns the authenticated account with its organization memberships.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "email": "string",
  • "organizations": [
    ]
}

List organizations

Lists the organizations the authenticated account belongs to.

query Parameters
offset
integer (Offset) >= 0
Default: 0
limit
integer (Limit) [ 1 .. 100 ]
Default: 100

Responses

Response samples

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

Create an organization

Creates an organization; the caller becomes its owner.

Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 64 ] characters
category
string (Category) <= 32 characters
Default: "personal"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "category": "personal"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "displayName": "string",
  • "category": "string",
  • "role": "string"
}

Get an organization

path Parameters
org_id
required
string (Org Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "displayName": "string",
  • "category": "string",
  • "role": "string"
}

Update an organization

Updates the organization's display name and/or category. Requires admin or higher.

path Parameters
org_id
required
string (Org Id)
Request Body schema: application/json
required
displayName
required
string (Displayname) [ 1 .. 64 ] characters
Category (string) or Category (null) (Category)

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "category": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "displayName": "string",
  • "category": "string",
  • "role": "string"
}

Delete an organization

Permanently deletes the organization. Requires owner.

path Parameters
org_id
required
string (Org Id)

Responses

Response samples

Content type
application/json
null

List organization members

path Parameters
org_id
required
string (Org Id)
query Parameters
offset
integer (Offset) >= 0
Default: 0
limit
integer (Limit) [ 1 .. 100 ]
Default: 100

Responses

Response samples

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

Change a member's organization role

Requires admin or higher. Only owners can grant the owner role.

path Parameters
org_id
required
string (Org Id)
member_user_id
required
string (Member User Id)
Request Body schema: application/json
required
role
required
string (Role)

One of: owner, admin, member.

Responses

Request samples

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

Response samples

Content type
application/json
null

Remove a member from the organization

path Parameters
org_id
required
string (Org Id)
member_user_id
required
string (Member User Id)

Responses

Response samples

Content type
application/json
null

List projects in an organization

path Parameters
org_id
required
string (Org Id)
query Parameters
offset
integer (Offset) >= 0
Default: 0
limit
integer (Limit) [ 1 .. 100 ]
Default: 100

Responses

Response samples

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

Create a project

Requires admin or higher.

path Parameters
org_id
required
string (Org Id)
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 64 ] characters

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "displayName": "string",
  • "organizationId": "string"
}

Get a project

path Parameters
project_id
required
string (Project Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "displayName": "string",
  • "organizationId": "string"
}

Update a project

Requires admin or higher.

path Parameters
project_id
required
string (Project Id)
Request Body schema: application/json
required
displayName
required
string (Displayname) [ 1 .. 64 ] characters

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "displayName": "string",
  • "organizationId": "string"
}

Delete a project

Requires organization owner.

path Parameters
project_id
required
string (Project Id)

Responses

Response samples

Content type
application/json
null

Keys

Endpoints for managing API keys.

API keys are used to authenticate requests to the Solti API. They can be created, listed, updated, and deleted by users with the appropriate permissions.

API keys can have one of the following roles:

  • admin: Full access to all Solti API endpoints, including sensitive operations such as managing API keys and connections.
  • developer: Access to major Solti API endpoints sufficient for most development tasks.
  • viewer: Read-only access to Solti API endpoints, suitable for monitoring and auditing purposes.

Create a new API key

Creates a new API key for programmatic access to the Solti API.

Required role: "admin".

Request Body schema: application/json
required
name
required
string (Name) [ 3 .. 50 ] characters ^[a-zA-Z0-9][a-zA-Z0-9_-]*$

Human-readable name of the API key. The name must be between 3 and 50 characters long, start with an alphanumeric character, and can contain alphanumeric characters, underscores, or hyphens.

role
required
string (Role)
Enum: "admin" "developer" "viewer"

Role to assign to the API key

Expires At (string) or Expires At (null) (Expires At)

Optional expiration timestamp

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "role": "admin",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "value": "string",
  • "role": "admin",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z"
}

List API keys

List API keys given the provided filters.

Required roles: "viewer" or higher.

query Parameters
Name (string) or Name (null) (Name)

Filter by human-readable name

Offset (integer) or Offset (null) (Offset)
Default: 0

Number of items to skip

Limit (integer) or Limit (null) (Limit)
Default: 50

Maximum number of items to return

"created_at" (string) or Sort By (null) (Sort By)

Field to sort by

Sort Order (string) or Sort Order (null) (Sort Order)

Sort order

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ],
  • "total": 0,
  • "offset": 0,
  • "limit": 0
}

Get an API key by ID

Retrieve an API key by its unique identifier.

Required roles: "viewer" or higher.

path Parameters
key_id
required
string (Key Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "role": "admin",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Update an API key

Update an existing API key's attributes.

Required role: "admin".

path Parameters
key_id
required
string (Key Id)
Request Body schema: application/json
required
Role (string) or Role (null) (Role)

New role for the API key

Responses

Request samples

Content type
application/json
{
  • "role": "admin"
}

Delete an API key

Delete an existing API key.

Required role: "admin".

path Parameters
key_id
required
string (Key Id)

Responses

Connections

Endpoints for managing Solti connections.

Connections are used to store configuration for external systems. They can be created, listed, updated, and deleted by users with the appropriate permissions.

Create a new connection

Creates a new Solti connection. Duplicate names within a project return 409 Conflict.

Required role: "admin".

Request Body schema: application/json
required
name
required
string (Name) [ 3 .. 50 ] characters ^[a-zA-Z0-9][a-zA-Z0-9_-]*$

Human-readable name of the connection. The name must be between 3 and 50 characters long, start with an alphanumeric character, and can contain alphanumeric characters, underscores, or hyphens.

type
required
string (Type)

Type of connection (aws)

Value: "aws"
access_key_id
required
string (Access Key Id)

AWS access key ID

secret_access_key
required
string (Secret Access Key)

AWS secret access key

Responses

Request samples

Content type
application/json
Example
{
  • "name": "string",
  • "type": "aws",
  • "access_key_id": "string",
  • "secret_access_key": "string"
}

Response samples

Content type
application/json
Example
{
  • "name": "string",
  • "type": "aws",
  • "access_key_id": "string",
  • "secret_access_key": "string"
}

List connections

List Solti connections given the provided filters. Credentials are always redacted.

Required roles: "viewer" or higher.

query Parameters
Name (string) or Name (null) (Name)

Filter by human-readable name

Offset (integer) or Offset (null) (Offset)
Default: 0

Number of items to skip

Limit (integer) or Limit (null) (Limit)
Default: 50

Maximum number of items to return

"name" (string) or Sort By (null) (Sort By)

Field to sort by

Sort Order (string) or Sort Order (null) (Sort Order)

Sort order

Responses

Response samples

Content type
application/json
{
  • "connections": [
    ],
  • "total": 0,
  • "offset": 0,
  • "limit": 0
}

Get a connection by name

Retrieve a Solti connection by its name. Inspecting decrypted credential values requires the "admin" role.

Required roles: "viewer" or higher.

path Parameters
name
required
string (Name)

Responses

Response samples

Content type
application/json
Example
{
  • "name": "string",
  • "type": "aws",
  • "access_key_id": "string",
  • "secret_access_key": "string"
}

Update a connection

Update an existing Solti connection's attributes (re-encrypts credentials when they change).

Required role: "admin".

path Parameters
name
required
string (Name)
Request Body schema: application/json
required
type
string (Type)
Default: "aws"

Type of connection (aws)

Value: "aws"
Access Key Id (string) or Access Key Id (null) (Access Key Id)

AWS access key ID

Secret Access Key (string) or Secret Access Key (null) (Secret Access Key)

AWS secret access key

Responses

Request samples

Content type
application/json
Example
{
  • "type": "aws",
  • "access_key_id": "string",
  • "secret_access_key": "string"
}

Response samples

Content type
application/json
Example
{
  • "name": "string",
  • "type": "aws",
  • "access_key_id": "string",
  • "secret_access_key": "string"
}

Delete a connection

Delete an existing Solti connection.

Required role: "admin".

path Parameters
name
required
string (Name)

Responses

Jobs

Endpoints for submitting and managing workloads.

A workload is a declarative container task that Solti routes to the most cost-effective cloud VM via Scarcity. Jobs can be submitted as JSON or YAML.

Submit a workload

Submits a declarative workload definition (JSON or YAML body).

  • If name is provided it must be unique within the project (otherwise 409 Conflict).
  • If namePrefix is provided, a unique name is generated as <prefix>-<random suffix>.
  • If neither is provided, a Notion-like unique name is auto-generated (e.g. tidal-star-1234).

Required roles: "developer" or higher.

Responses

Response samples

Content type
application/json
{
  • "job_id": "string",
  • "name": "string",
  • "status": "queued"
}

List jobs

List jobs in the project, sorted by creation date (newest first). Supports filtering by status, tag (repeatable), and label as "key=value" (repeatable).

Required roles: "viewer" or higher.

query Parameters
Status (string) or Status (null) (Status)

Filter by status

Array of Tag (strings) or Tag (null) (Tag)

Filter by tags (repeatable)

Array of Label (strings) or Label (null) (Label)

Filter by labels as "key:value" pairs (repeatable; "key=value" accepted for compatibility)

Offset (integer) or Offset (null) (Offset)
Default: 0

Number of items to skip

Limit (integer) or Limit (null) (Limit)
Default: 50

Maximum number of items to return

Responses

Response samples

Content type
application/json
{
  • "jobs": [
    ],
  • "total": 0,
  • "offset": 0,
  • "limit": 0
}

Get a job by UUID or name

Retrieve a job's state, execution metadata, timing, VM status, cost metrics, retry status, and any logged error summaries. The path parameter accepts either the job's unique UUID or its unique name.

Required roles: "viewer" or higher.

path Parameters
job_id_or_name
required
string (Job Id Or Name)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "name": "string",
  • "namePrefix": "string",
  • "status": "queued",
  • "credentials_status": "empty",
  • "vm_status": "nonassigned",
  • "image": "string",
  • "command": [
    ],
  • "args": [
    ],
  • "env": {
    },
  • "volumes": [
    ],
  • "resources": { },
  • "cloud": [
    ],
  • "region": [
    ],
  • "labels": {
    },
  • "tags": [
    ],
  • "retry_count": 0,
  • "max_retries": 0,
  • "selected_provider": "string",
  • "selected_region": "string",
  • "selected_instance_type": "string",
  • "vm_instance_id": "string",
  • "ip_address": "string",
  • "estimated_cost": 0,
  • "actual_cost": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "last_heartbeat_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "ended_at": "2019-08-24T14:15:22Z",
  • "timeout_seconds": 3600,
  • "error_message": "string"
}

Cancel a job

Cancels a queued, booting, or running job. The scheduler detects the transition and triggers immediate VM teardown. The path parameter accepts either the job's unique UUID or its unique name.

Required roles: "developer" or higher.

path Parameters
job_id_or_name
required
string (Job Id Or Name)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "name": "string",
  • "namePrefix": "string",
  • "status": "queued",
  • "credentials_status": "empty",
  • "vm_status": "nonassigned",
  • "image": "string",
  • "command": [
    ],
  • "args": [
    ],
  • "env": {
    },
  • "volumes": [
    ],
  • "resources": { },
  • "cloud": [
    ],
  • "region": [
    ],
  • "labels": {
    },
  • "tags": [
    ],
  • "retry_count": 0,
  • "max_retries": 0,
  • "selected_provider": "string",
  • "selected_region": "string",
  • "selected_instance_type": "string",
  • "vm_instance_id": "string",
  • "ip_address": "string",
  • "estimated_cost": 0,
  • "actual_cost": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "last_heartbeat_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "ended_at": "2019-08-24T14:15:22Z",
  • "timeout_seconds": 3600,
  • "error_message": "string"
}

Cronjobs

Endpoints for managing periodic task templates.

All cron expressions are evaluated strictly in UTC. When a cronjob triggers, the scheduler spawns a new standard job from its job_definition template.

Create a cronjob

Creates a periodic task definition using a UTC crontab expression and a job_definition configuration template.

Required role: "admin".

Request Body schema: application/json
required
name
required
string (Name) [ 3 .. 100 ] characters ^[a-z0-9][a-z0-9-]*$

Unique name inside the project namespace (slug format)

cron_spec
required
string (Cron Spec)

Standard cron expression evaluated in UTC (e.g. '0 2 * * *')

required
object (JobDefinition)

Job configuration to spawn the job from

is_active
boolean (Is Active)
Default: true

Whether the scheduler should trigger this cronjob

Project Id (string) or Project Id (null) (Project Id)

Project ID (internal use)

Organization Id (string) or Organization Id (null) (Organization Id)

Organization ID (internal use)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "cron_spec": "string",
  • "job_definition": {
    },
  • "is_active": true,
  • "project_id": "string",
  • "organization_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "name": "string",
  • "cron_spec": "string",
  • "job_definition": { },
  • "is_active": true,
  • "last_triggered_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List cronjobs

Lists active and inactive cronjobs for the project, sorted by creation date.

Required roles: "viewer" or higher.

query Parameters
offset
integer (Offset) >= 0
Default: 0

Number of items to skip

limit
integer (Limit) ( 0 .. 200 ]
Default: 50

Maximum number of items to return

Responses

Response samples

Content type
application/json
{
  • "cronjobs": [
    ],
  • "total": 0,
  • "offset": 0,
  • "limit": 0
}

Get a cronjob by UUID or name

The path parameter accepts either the cronjob's unique UUID or its unique name.

path Parameters
cronjob_id_or_name
required
string (Cronjob Id Or Name)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "name": "string",
  • "cron_spec": "string",
  • "job_definition": { },
  • "is_active": true,
  • "last_triggered_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a cronjob

Updates cronjob parameters (e.g. toggling is_active, changing cron_spec, or replacing job_definition) without recreating the resource. The path parameter accepts either the cronjob's unique UUID or its unique name.

Required role: "admin".

path Parameters
cronjob_id_or_name
required
string (Cronjob Id Or Name)
Request Body schema: application/json
required
Cron Spec (string) or Cron Spec (null) (Cron Spec)

New cron expression (UTC)

JobDefinition (object) or null

New job configuration template

Is Active (boolean) or Is Active (null) (Is Active)

Toggle scheduler activity

Project Id (string) or Project Id (null) (Project Id)

Project ID (internal use)

Organization Id (string) or Organization Id (null) (Organization Id)

Organization ID (internal use)

Responses

Request samples

Content type
application/json
{
  • "cron_spec": "string",
  • "job_definition": {
    },
  • "is_active": true,
  • "project_id": "string",
  • "organization_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "name": "string",
  • "cron_spec": "string",
  • "job_definition": { },
  • "is_active": true,
  • "last_triggered_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a cronjob

Deletes a cronjob. The path parameter accepts either the cronjob's unique UUID or its unique name.

Required role: "admin".

path Parameters
cronjob_id_or_name
required
string (Cronjob Id Or Name)

Responses

Resources

List available storages

query Parameters
Connection Id (string) or Connection Id (null) (Connection Id)

Filter by a specific connection ID.

Responses

Response samples

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

List available repositories

query Parameters
Connection Id (string) or Connection Id (null) (Connection Id)

Filter by a specific connection ID.

Responses

Response samples

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

List available virtual machine pools

query Parameters
Connection Id (string) or Connection Id (null) (Connection Id)

Filter by a specific connection ID.

Responses

Response samples

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